Programming constructs of the scripting language

Page updated 1/10/98.

PM Scripting Language: programming statements.

Besides the standard API commands and queries, PM Scripting Language (PMSL) defines a number of programming statements ( refered to as operators in this document or as controls in Hans's book). Operators change the order of the execution of a script or the way variables are computed. Each PMSL operator begins (ignoring leading spaces and tabs) a separate line of the script. If PMSL recognizes an operator it processes the script line internally and then goes on to the next line of the script. Otherwise PMSL regards each line as a query (if first 3 chars are 'get' ) or as a command. All commands and queries are passed to PageMaker. In case of a query, PageMaker's reply is retrieved. Warning: Scripting Language sends all non-operator commands to the PageMaker. Therefore any illegal or garbage string which may occur in the script will be passed to PageMaker as a script command which usually stops the script execution.
This is the list PMSL operators:
@
break
breakpoint
call
caseof
default
else
eleseif
endif
endloop
endsub
endswitch
endwhile
errorchecking
getargs
getplatform
getprocparam
gettime
getyesno
gosub
goto
if
include
kill
label
log
logappend
logbegin
logend
logremove
loop
message
read
readadvance
readbegin
readend
rem
repeat
return
set
sub
switch
try
until
updateprocparam
var
while

New operators implemented in Script Engine v 3.5

abort
continue
dir
execute
getnameof
getokcancel
getscriptver
getyesnocancel
readline
system
callback
getpanestate
setpanestate

Operator: @

Syntax: @ <script line>
The @ operator sends the <script line> directly to PageMaker with NO processing. The following example illustrates the issue:
@ findattr "Any", "Any", -2, boldstyle+underlinestyle
This script line should set the Find attributes to search for both bold and underline typestyles. Normally PMSL would try add the boldstyle and underlinestyle arguments before sending the script line to the PageMaker. It would cause an error in calculations unless variables 'boldstyle' and 'underlinestyle' are properly defined in the script. The @ operator tells PMSL to send the line with no processing.
Another possible reason for using @ could be a performance considerations, especially when command is used within loop. Be sure, that command listed after @-prefix does not contains variables and numeric computations so that PageMaker could handle it.
At least one white space character is required between @ and the rest of the line.

Operator: set

Syntax: set <expression> >> <list of variables>
Obsolete way of assignment. Supported for backward compatibility.
For example, instead of
set x + 1 , y + 1 >> xplus,yplus
one may consider using
xplus,yplus = x + 1 , y + 1

Operator: message

Syntax: message <string>
Here <string> is any quoted string or any expression that evaluates into quoted string.
Operator message halts execution of a script and displays text in a dialog box. An OK button allows the user to resume execution of the script.
Example:
getpagenumber >> N, ...
message "Document contains "+quote(N)+" pages."
When applied to a new default document script displays the following message:
Document contains 1 pages.
PMSL will display a single message box for consecutive message statements, for example:
message " ****************************************** "
message " * Your script begins * "
message " ****************************************** "
displays just one message dialog .

Operator: getyesno

Syntax: getyesno >> <variable>
The 'OK' button normally displayed in a message box can be replaced with a pair of 'YES' / 'NO' buttons by using the getyesno operator following a message statement(s). The user's choice (i.e. YES or NO) will be assigned to a variable indicated in the getyesno line.
Example:
message "Memory is extremely low."
message "Do you want to cancel this script?"
getyesno >> yesno
if yesno = YES
return
endif
The variable 'yesno' will be assigned a value of YES or NO depending on the user's choice. The if statement tests the returned value and branches accordingly. (Note: Values YES and NO are in upper case and not enclosed in quotes.)

Operators: readbegin, readend

Syntax: readbegin <filename>
Syntax: readend
Operator readbegin opens file for input and sets the file pointer at the beginning of the file. PMSL provides only sequential access to the file by operators read and readadvance. PMSL admits no more then one opened input file at a time. Parameter <filename> should be a quoted string. On Windows file name is relative to the location of the current script unless a parameter <filename> contains name of the drive. On Macintosh PMSL always tries first to consider parameter as absolute path which starts with a name of the volume. When fails to do so, PMSL tries to open file in the folder of currently executed script. If <filename> starts with ':' then char ':' is ignored, but everything after ':' is considered as relative to the location of the current script from the very beginning. Current implementation of PMSL on Windows platform does not recognize long file names.
The file remains opened for input until operator readend closes it.

Operator: read

Syntax: read >> var1,var2, . . . , varN
Operator read presumes that the current line of the input file is a list of comma separated tokens. Operator reads tokens one by one and assigns them to variables var1,var2, . . . , varN. Every variable including the last one gets just one token. When executing operator read, file pointer can not go to the next line of the input file. If the line has not enough tokens, remaining variables get value of an empty string.

Operator: readadvance.

Syntax: readadvance nLines,nTokens
Moves file pointer nLines forward ( current line counted as the first one) and after that moves file pointer yet nTokens forward. When moving nTokens forward remains in the same line. If line is too short file pointer stops before carriage return.

Operators: logbegin , logend , logappend

Syntax: logbegin <filename>
Syntax: logappend <filename>
Syntax: logend
logbegin opens for output a file specified as a parameter. All subsequent commands log will write there arguments into this file. The file is opened until command logend closes it. The name and path specified as a parameter of the logbegin operator should be quoted. On Windows path name is relative to the location of the current script unless parameter <filename> contains name of the drive . On Macintosh PMSL always tries first to interpret parameter as absolute path which starts with a name of the volume. When fails to do so, writes log file into the directory of the current script. Current implementation of PMSL on Windows platform does not recognize long file names.
logend closes the log opened by matching logbegin operator.
logbegin ... logend segnents may be nested, in this case internal logbegin ... logend is ignored, so that first opened log overrules other log files which happen to be opened inside the widest logbegin...logend range.
Logappend works similar to logbegin, except it wont delete the specified file but rather set it up for appending.

Operator: log

Syntax: log <expression>
log calculates <expression> if necessary (quoted expression is expected) and writes it into the log which is currently opened by logbegin command. Outside of the logbegin ... logend range operator log works exactly as operator message does.
Warning: On Windows platform an error in the log line ( if occured ) does not error out the script. Expected behaviour - script is interrupted. This is a bug to be fixed in future versions.

Operator: logremove

Syntax: logremove <filename>
Finds and delete specified file.

Operators: if , endif

Syntax: if <expression>
Syntax: endif
The <expression> will be evaluated. If the result of calculation is 0 ( false) , all script lines between the if and endif operators will be skipped. Programming constructs if .... endif may be nested; PMSL will find right endif.
Example:
getpagesize >> x,y
if x > y
z = x
x = y
z = y
endif
pagesize x , y
This script will convert a wide pagesize pub to a tall pub, but will have no effect on tall pagesize pubs.

Operators: elseif , else

Syntax: elseif <expression>
Syntax: else
Operators elseif or else may be placed between if and endif so that script performs some actions in case the if statement founds it's condition to be false.
Example:
getpagenumber >> n, ...
if n = -3
message " This is a left master page."
elseif n = -4
message " This is a right master page."
else
message " This is a regular page."
endif
Note that if's and endif's in a script should match. Thus, elseif is not exactly the same as else and if on two consequtive lines of hr script.
Example:
getpagenumber >> n, ...
if n = -3
message " This is left master page."
else
if n = -4
message " This is right master page."
else
message " This is regular page."
endif
endif

Operators: goto , label

Syntax: goto <expression>
Syntax: label <value>
goto evaluates the <expression> and passes the control to the next label statement where <value> matches the evaluated <expression>.
Operator goto can not transfer control backwards. If a script contains several identical labels the first matching label will be founded.
Example:
getfont >> fontname
getfontlist >> fontlist
if "Helvetica" # fontlist
font "Helvetica"
goto done
endif
if "Helvetica-Narrow" # fontlist
message "Font \"Helvetica-Narrow\" substituted instead of \"Helvetica\" "
font "Helvetica-Narrow"
goto done
endif
message " Default font" + fontname + "will be used instead of undiscovered \"Helvetica\" "
label done
newstory 1,1
textenter "How do you like this font?"
deselect
font fontname
This script tries to set the font "Helvetica" or a similar font and then uses the default font only if it fails to do so. The last line of the script restores the default font.

Operators: repeat , until

Syntax: repeat
Syntax: until <expression>
All statements from repeat to until form a loop. The loop will be repeated at least once. While <expression> evaluates to 0 the loop will be repeated. Repetition of the loop stops as soon as <expression> evaluates to a non-zero value. Nested loops are also possible. Use operator break for emergent exit from the loop.
Example:
i = 0
repeat
i = i+1
new i
until i = 10
This script opens 10 new pubs with 1,2,...10 pages correspondingly.
Example:
getcolornames >> colorlist
repeat
set colorlist => somecolor,colorlist
message "Color " + somecolor + " discovered."
until empty(colorlist)
This script shows in its message box, the names of all colors defined in a pub.
How this script works: Every iteration of
set colorlist >> somecolor,colorlist
sets 'somecolor' to the first color in 'colorlist' and then dumps the remainder of the list back into 'colorlist', which gets one term shorter each time. After the last color is displayed, 'colorlist' is exhausted, (i.e. is equal to empty string). The empty() function, returns '1' at this point and operrator until interrupts the loop.

Operators: while , endwhile

Syntax: while <expression>
Syntax: endwhile
All statements between these two statements form a loop. The loop will be executed until <expression> evaluates to 0. Unlike the repeat ... until loop, this loop checks that <expression> is not 0 before entering the loop. If <expression>'s initial value is 0 the loop will be skipped altogether.
Use operator break for emergent exit from the loop.

Operators: loop , endloop

Syntax: loop <variable> = <from>,<to>
Syntax: endloop
<from> and <to> stand for the beginning and ending value of the variable. All statements between loop and endloop will be repeated for every value of <variable> starting with <from>, and ending when <variable> is greater than <to>, incrementing by 1 with each iteration. Loop will be skipped if value of <from> is greater then value of <to>. The value of <variable> can be used inside and after the loop. (Note: loop is similar to the BASIC For statement.)
Use operator break for emergent exit from the loop.
Example:
editstory
loop i = 1 , 10
textenter ""(i)+", "
endloop
This example enters the numbers from 1 to 10 in a story in the story editor.

Operators: switch , caseof , endswitch , default

Syntax: switch < expression>
Syntax: caseof < expression>
Syntax: endswitch
Syntax: default
Switch evaluates <expression> and looks for caseof staement which has the same value of the <expression>. If such a statement is found then the execution of a script resumes starting with the line immediately following the caseof statement. If matching caseof is not found then switch looks for default statement in the switch .. endswitch scope. Normally, script segment following the caseof statements should be completed by break command to prevent falling thru another caseof statement.
Example:
getpagenumber >> n,...
switch n
caseof -3
message "Left master page"
break
caseof -4
message "Right master page"
break
default
message "Regular page"
endswitch

Operator: break

Syntax: break <expression>
This operator breaks a loop or switch statement if <expression> evaluates to TRUE. Ignored if <expression> evaluates to 0 ( FALSE ). Note that when break is used without parameters <expression> evaluates to empty string which is considered as TRUE. Operator break may be used for premature exit from repeat ... until , while ... endwhile and loop ... endloop loops.

Operators: call ( or gosubfile) , return

Syntax: call filename.ext , <list of parameters> >> <list of vars>
or
gosubfile filename.ext,<list of parameters> >> <list of vars>
Syntax: return <expression>
call evaluates the list of parameters and starts running the script from the file "filename.ext". This new script runs as a subroutine of the parent script containing call operator. It can read the same variables that were defined at the moment subroutine was called and can add local variables for reading and writing. In case of attempt to change non-local variable PMSL will create local variable with the same name. All local variables are forfeited upon exit from a subroutine. When the return statement is encountered in the script, "filename.ext" evaluates <expression> in this statement, assigns the result to the variable(s) <list of vars> as posted in call statement and passes control to the statement following the call statement in the parent script. Recursive calls are also possible, (but can be dangerous.)
If return occurs in the script initially launched by user, then the script terminates. Using return is the only legal way to finish the script, (i.e. every script should contain a terminating return).
Depending on the implementation <expression> may be used in a "good by" message box which indicates to a user that script has been completed.
Depending on the implementation PMSL may or may not post an alert if user forgets to put 'return' at the end of a script.

Operator: include

Syntax: include filename.ext,<list of parameters> >> <list of vars>
Same as call, but local variables are not destroyed upon exit from the subroutine.

Operators : gosub , sub , endsub

Syntax: gosub <name of subroutine> ,<list of parameters> >> <list of vars>
Syntax: sub <name of subroutine>
Syntax: endsub
Unlike operator call the operator gosub looks for subroutine in the current file. Subroutine is defined as a script segment between sub and endsub operators. Subroutine may be defined in any place of the script ( usually at the beginning or at the end of the script.). When sub statement occurs during normal execution of the script the sub .. endsub segment of the script is skipped.
The following script displays "1","2","3" in three consequtive message boxes:
n = 0
sub test
message quote(n)
return
endsub
loop n = 1,3
gosub test
endloop
return

Operator: getprocparam, getargs

Syntax: getprocparam >> <list of values>
Syntax: getargs >> <list of values>
getprocparam is used within a subroutine to acquire parameters passed to the subroutine in a call, gosubfile, include or gosub operator. Operators getprocparam and getargs assign parameters to the variables posted to the right of arrow. Operator getprocparam produces the name of the file or subroutine on the first place and after that parameters passed to the subroutine. Operator getargs produces parameters only.
Example:
sub cube
getprocparam >> ...,arg // Script line ' getargs >> arg ' would have the same effect
return arg*arg*arg
endsub
s = 0
loop n = 1,10
gosub cube,n >> n3
s = s + n3
endloop
return s
This script calculates the sum 1*1*1 + 2*2*2 + . . . + 10*10*10.

Operator: var

Syntax: var <list of variables.>
Similar to Dim statement in VB. Not required by PMSL, but useful for readability.

Operator: kill

Syntax kill <list of variables>
kill removes all variables posted in the list from memory. If list contains a name of a variable which does not currently exist, this name is ignored. kill is only implemented for memory management purposes.
Example:
a,b,c = 1,2,3
message quote(a ,b ,c)
kill a,c,d
message quote(a,b,c)
return
The first message in this example displays '1,2,3' while the second message displays 'a,2,c'. The variables a and c are killed so that only b will be substituted.
In a subroutine, kill only effects local variables.
Some implementations may ignore this command.

Operator: errorchecking

Syntax:
errorchecking on
or
errorchecking off
Depending on the state of this toggle, PMSL tests, following each command or query, to see if PageMaker returns an error. Checking is done using the query "getlasterrorstr". The reply from this query is displayed if an error occurs and the script is aborted. The default state of errorchecking is on. If errorchecking is off Scripter ignores invalid commands and returns a void reply for invalid queries. (It is the users responsibility to test for errors explicitly, in this state.) Switching errorchecking off may slightly increase performance and allows the programmer to test for invalid commands and queries or arguments without aborting the script. (Note: It is advisable to leave errorchecking on for normal scripting. When disabling errorchecking to test for an error condition, remember to re-enable as soon as the test is complete.)
Example:
errorchecking off
font "Arial"
font "Helvetica"
errorchecking on
This script assigns to a selected text font "Helvetica" if this font installed, otherwise it assigns font "Arial" If neither "Helvetica" nor "Arial" is installed then script leaves text as is. Anyway, script is not aborted when Pagemaker command 'font' fails.

Operator: try

Syntax: try <PageMaker command>
Operator try supresses errorchecking while executing just one command.
Example:
try font "Arial"
try font "Helvetica"
This script does the same as the script in previous example.

Operator: breakpoint

Syntax: breakpoint <expression>
If a script is traced, then the breakpoint operator evaluates <expression> and if the result differs from 0 suspends the normal execution of a script switching Scripter to step mode. The operator is used for debugging of a script. A script can be run by "Trace script" command on the Script Palette with subsequent choice of the and "Run" option. In this case the script will run until the breakpoint operator is encountered. The programmer can then step thru the suspect lines and then re-initiate the run mode to complete the remainder of the script.
Operator breakpoint is ignored if script is executed without tracing.

Operator: gettime

no parameters required
replies: year, month (1 .. 12), date ( 1.. 31), hour, min, sec, miliseconds , tickcount
Value of tickcount depends on platform: on WIN it is milisecs since system started; on MAC it is sixties of seconds since system started. Miliseconds are returned only for Windows, for Mac this value is always 0.

Operator: getplatform

Replies: MACINTOSH or WINDOWS
Example:
getplatform >> def
if def = WINDOWS
log "Executing Windows script."
elseif def = MACINTOSH
log "Executing Macintosh script"
endif

Operator: rem

If the first word in a line is rem , then the line is ignored. Such a line may be used for comments.
One may also use -- or // for commenting the script. Unlike rem , -- or // can comment part of the line, following these symbols.

Operator: abort

Cancels execution of the current script and all parent scripts. When using 'Execute Script' command in Script Palette 'abort' forces PMSCRIPT to quit, when using 'Trace Script' menu item in the Script Palette 'abort' leaves only two choices: "Reset" ( to start again from the very beginning ) and "Close". ( to close the tracing application )

Operator: continue

Operator 'continue' may be used inside loops defined by any of the folowing construct pairs: loop .. endloop, repeat .. until, while .. endwhile. Operator 'continue' forces to skip all lines of the script between 'continue' and 'endloop' or 'endwhile' or 'until', whichever comes first. If 'continue' is used with a parameter, then parameter is evaluated first and if the result is 0 then command 'continue' is ignored.
Example:
editstory
loop i = 1,Len(FontList)
try font FontList(i)
getlasterror >> err
continue err // do nothing since font does not exist in a document
textenter FontList(i)
textenter "
"
endloop

Operator: dir

Operator 'dir' returns list of the files in a directory which satisfy search pattern specified in the parameter. Files are retrieved as a comma separated list of the quoted file names.
Example 1:
dir "c:\adobe\pm65\rsrc\usenglsh\plugins\scripts\Dialog Builder\*.spt" >> List
message str(List)
return

The following list is prompted:
"Open Dialog Template.spt", "Align Controls.spt","Adjust Dialog Box.spt","Test Dialog.spt","Save Dialog.spt"

If quoted string used as a parameter ends with '+' sign then operator dir searches only subdirectories.
Example 2:
dir "c:\adobe\pm65\rsrc\usenglsh\plugins\scripts\*.*+" >> List
message Str(List)
return

The following list is prompted:

"Document Layout","Online","Template","Run Plug-ins","Element","Images","Printing","Text","Color","Dialog Builder"

Example 3:
dir "c:\adobe\pm65\rsrc\usenglsh\plugins\scripts\D*.*+" >> List
message Str(List)
return

The following list is prompted:

"Document Layout","Dialog Builder"

Operator: execute

Operator 'execute' expectes as a parameter quoted line of the script. Quotes will be removed and script line executed.
Example:
execute "x = 3"
message Str(x)
return
Prompted: 3

Operator: getnameof

Syntax:
getnameof currentscript
getnameof currentscriptdir
Operator returns name ( including path ) of the curent script or path to the directory in which curently executed script resides. Unlike in previous version, names returned by the operator are always quoted. - paying a tribute to Win32 file system.
Example:
getnameof currentscript >> x
getnameof currentscriptdir >> y
message x
message y
return

Prompted:
c:\adobe\pm65\rsrc\usenglsh\plugins\scripts\example.spt
c:\adobe\pm65\rsrc\usenglsh\plugins\scripts

Use variable watch functionality of the PMTRACE to see that x = "c:\adobe\pm65\rsrc\usenglsh\plugins\scripts\example.spt" and y = "c:\adobe\pm65\rsrc\usenglsh\plugins\scripts"

Operators: getyesnocancel, getokcancel

These operators work and should be used similar to the operator 'getyesno'.
Operator getyesnocancel puts 3 buttons into a message box: "Yes","No","Cancel". It returns eiher YES or NO or CANCEL accordingly to user's input.
Operator getokcancel puts 2 buttons into a message box: "OK" and "Cancel". It returns either OK or CANCEL accordingly to user's input.

Operator: getscriptver

In new version of PMSCRIPT/PMTRACE this operator returns 3.5
It returns empty string in earlier released PMSCRIPT/PMTRACE.
Reply can be used to prevent scripts with new functionality from running on earlier versions of the script engine. For example:
getscriptver >> ver
if empty(ver)
message "Sorry, the script can not run on this version of the script engine."
endif
if ver < 3.5
message "Sorry, the script can not run on this version of the script engine."
endif
return

Operator: readline

This operator complements read operators in eralier versions of the script engine. It reads contents of the text file opened for reading from the current position of the file pointer to the end of the line. The result is presented as a quoted string. After string is read, the file pointer is moved to the beginning of the next line.

Operator: system

The operator requires quoted string as a parameter. This parameter is considered and executed as a MSDOS command.
Example:
system "copy c:\temp\file1.ext c:\temp\file2.ext"
Note that in Script Engine 3.5 every system command is executed in its own DOS shell i.e. script
system "c:"
system "cd\ "
system "copy config.sys config.bat"
will not work as a batch file.

Operator: callback

Syntax: callback <Name of a subroutine>

Operator callback is applicable only within dialogbegin .. dialogend construct immediately after a script line specifying a control. When callback operator follows the control it modifies the default behaviour of the control. When user hits the control Scripter searches and launches a subroutine with the name specified in a callback statement. This subroutine can use operators getpanestate and setpanestate to modify other dialog controls. The dialog persists while callback subroutine is executed. After subroutine is done, user regains the control over the dialog. Note that callback subroutine may deploy its own dialogs thus implementing nested dialogs ( up to 12 nesting ones ). See an example in the script Import Styles.
( dialogbegin .. dialogend construct not yet addressed in this document, see the book "Adobe PageMaker Scripting" by Hans Hansen, pp 115 - 124 )

Operator: getpanestate

Syntax: getpanestate <N>
where N is a number of the control when counting controls between dialogbegin and dialogend statement. Count starts with 1.
This operators replies state of the control. State of the control is a string, but the content of the string depends on the type of the control.

Operator: setpanestate

Syntax: setpanestate <N>,<state of the control>
where N is a number of the control when counting controls between dialogbegin and dialogend statement. Count starts with 1.
This operators sets the control into the specified state. Format of the parameters should match the format of the reply obtained by getpanestate, however certain fields may be altered.

State of the pane is not just short, one token per control information returned by dialogend command. It contains caption of the control, check/unchecked and enabled/disabled flags. To learn more about control states, run the script pasted below. Feel free to alternate dialogbegin ... dialogend construct in the main script first, but do not alternate a subroutine "Tutorial"

dialogbegin -100,-100,100,100,"Test new operators"
listbox 5,5,95,65,"item1","item2","item3"
listboxmulti 105,5,195,65,"item1","item2","item3"
static 5,70,195,90,"This is a static text. "
radiobutton 5,105,95,115,"radiobutton 1",1
radiobutton 5,120,95,130,"radiobutton 2",0
checkbox 5,135,95,145,"Checkbox",1
radiobutton 105,105,195,115,"disabled radiobutton 1",1,0
radiobutton 105,120,195,130,"disabled radiobutton 2",0,0
checkbox 105,135,195,145,"Disabled Checkbox",1,0
pushbutton 5,150,95,170,"Enabled pushbutton",dontcare,1
pushbutton 105,150,195,170,"Disabled pushbutton",dontcare,0
pushbutton 20,175,180,195,"Tutorial: Invoke callback script"
callback Tutorial
dialogend
return

sub Tutorial
dialogbegin -80,-30,120,10,""
static 3,3,120,30,"To see the state of a control enter the number of the control and hit the button"
edit 125,3,155,20,"1"
pushbutton 160,3,195,20,"OK"
dialogend >> bHit,...,N,...
if not(bHit="OK") + (N="")
return
endif
N = unquote(N)
if not(isnumber(N))
return
endif
getpanestate N >> state
message ""(state)
endsub