Environment


Environment		Commands

Commands

Virtually all SIR2002 features can be run either from menus or from commands. A single command can be entered through the DBMS-MENU but normally commands are run as scripts or procedures. There are a specific set of commands which can be used when creating procedures. These commands can be anywhere in the input set and can be used to:

Include comments and remarks.
Modify the input text. As input is read, it can be modified by:
- Global variable substitution.
  Global variables are named variables that have a value, primarily used for text substitution. If input text includes the name of the global variable enclosed in angle brackets < >, the current value of the global variable is substituted into the text. Globals can be defined and assigned values with the GLOBAL and GCOMPUTE commands. There is also a set of predefined system globals which can be used for such things as today's date.
- Parameter substitution.
  Parameters can be specified when initiating a command stream and these can be used by the commands to set particular values.
- Text inclusion.
  The INCLUDE commands include text from a buffer, file or member at the point of the command. Text inclusion commands can appear within any input source including included text. The FINISH and PEND commands terminates processing of the current input source. PEND returns to the next higher level input source to resume execution. FINISH returns to the menus or ends a batch run.
- Text generation and repetition.
  Repetitive code can be generated with the DO REPEAT command. This takes a block of text and expands it. When the entire block has been expanded, the command processor begins processing the commands in the expanded block.
Control command processing.
Commands can be processed conditionally either through the block structured CIF (for Compile IF) command or by the logical tests which can skip to specified places in an input procedure. These control which commands are processed.
CIF sets conditions which either initiate or suspend processing of subsequent commands. When processing is suspended, commands are skipped until another CIF command halts skipping. The CIF TRUE & FALSE and CIF END subcommands allow conditional processing within a CIF.
Control output. Commands which control output and other settings include:

Comments and Remarks

Any text after a vertical bar (from that point to the physical end of the input line) is treated as comments. Command continuation lines are not affected by comments after a vertical bar. i.e. as long as the comment is at the end of the line, the command can be continued on a subsequent line.

The comment command can also be used.

COMMENT text

Inserts comment text. This is printed in the output listing. This is a command and therefore cannot appear between continuation lines for another command. The comment can have continuation lines.

REMARK 'text'

Writes a remark to the output file.

The printing of remarks and comments is controlled by PRINT BACK settings.

Global Variables

Global variables are named variables that have a value. These variables are global in the sense that they are stored in the environment externally to any specific routine. Global variables are primarily used for text substitution but also provide an easy and convenient method of passing small amounts of information between menus and programs.

Global variables have standard SIR2002 eight character names.

Globals can be defined and assigned values in four ways:

with the GLOBAL command
with the GCOMPUTE command
with the Globals option on the Settings Menu.
In VisualPQL programs with the GLOBALN and GLOBALS functions

If input text includes the name of the global variable enclosed in angle brackets < >, the current value of the global variable is substituted into the text. For example, suppose a global variable called RECNAME has the value PARTS assigned to it. If the following line is input:

PROCESS REC <RECNAME>

The value of the global variable RECNAME is substituted into this line before the VisualPQL compiler deals with it. The line that the compiler works with is:

PROCESS REC PARTS

Whenever a global variable is found in the input text enclosed in angle brackets, the current value of the variable is substituted in the text. This substitution happens at input time. If the program is compiled at one time and then run at some later time, the value of the global variable at run time is irrelevant.

Because the system employs a "read ahead" strategy to discover whether the next line is a continuation of the previous line, the value of the global variable is NOT available on the first line after the command that creates (or updates) the variable. For example:

PROGRAM
GLOBAL GREET = Hello World
WRITE <GREET>
END PROGRAM

This example does not write "Hello World" because the global variable was not set when the line WRITE <GREET> was read. Use the following:

GLOBAL GREET = Hello World
C    blank line for global setting
WRITE <GREET>

This example writes the greeting. Place a blank comment line after the global assignment to use the value immediately in the next subsequent command.

Global variables at run time

The value in a global variable can be tested in a program at run time by referencing it in a function. There are two VisualPQL functions NGLOBAL and SGLOBAL which read the run time value of a global variable; the GLOBALN and GLOBALS functions update the current value of a global variable. The S and N prefix/suffix refer to string variables or numeric variables. These functions happen at run time.

These functions can be used to pass parameters between two compiled programs; between a compiled program and a text procedure; between a text procedure and a compiled program; etc. The value can be used outside a program at compile time for straightforward text substitution and can be referenced inCIFand DO REPEAT commands.

GLOBAL

GLOBAL global_name = value [, global_name = value] ...

The GLOBAL command creates global variables and assigns values. Multiple global variables can be defined on a single GLOBAL command, in which case use a comma as the delimiter between global variable specifications.

The value of a global is held internally as text. By default, leading and trailing blanks are deleted. Leading and trailing blanks as well as commas can be specified by delimiting the value with the dollar sign ($). For example:

GLOBAL DATEGLOB = $   Jan 24, 1998$

Dollar signs can be preserved by repeating the dollar sign as in the following example where the value of the variable MONEY is A$41,500:

GLOBAL MONEY = $A$$41,500$

GCOMPUTE

GCOMPUTE global_varname = expression

Initialises a new global variable if it does not already exist or recalculates the value of the variable if it already exists.

The expression may contain:

string constants ( quoted strings )
string operators ( + )
numeric constants
numeric operators ( + , - , / , * , ** )
parentheses
global variable names

Note: GCOMPUTE differs from GLOBAL in that it evaluates the expression and may substitute values for globals in the expression. The GLOBAL command treats the value as literal text and does no evaluation.

System Globals

As well as global variables defined by the user there is also a set of system globals. The system global variables are:

CBLEVEL: The count of the number of times that the data dictionary of the current database has been updated.
CPTIME: The elapsed time in milliseconds since the beginning of the session.
DATE: The current date in the format 'MM/DD/YY'
DBNAME: The name of the current database
GERROR: The total number of errors in commands during the current session.
GWARNING: The total number of warnings issued during the current session.
LINECNT: The lines remaining on the current page on the output file.
LINEWID: The width setting of the output file.
MASTER: The name of the MASTER process controlling this session. If this is not a concurrent session, the value of this global is eight blanks.
PAGESIZE: The current setting of the number of lines per page for the current output device or file.
SIRCODE: The SIR license code.
SIRCUST: The SIR customer number.
SIRID: The SIR2002 release number.
SIRVER: The SIR2002 release version number.
SIREXP: The SIR license expiry date.
SYSPROC: The attribute that points to the system procedure file
TERROR: The count of task errors; the number of errors detected in the current run.
TIME: The current time in the format 'HH:MM:SS'
TWARNING: The count of task warnings; the number of warnings issued in the current run.

Parameter Substitution

Parameter substitution is similar to global variable text substitution but works with positional specifications rather than named variables.

Specify the parameter to be substituted in the text as a number inside angle brackets, such as <1> or <2>. When the set of text is RUN, supply the parameters to substitute as a list of values. The numbers specified on the text refer to the position of the parameter on the input list. Thus <1> refers to the first parameter, <2> the second and so on. The same number can be used multiple times in the input text if the same value is to be substituted. Separate each entry in the list with commas and enclose the whole list in parentheses. For example, suppose the following program:

RETRIEVAL
.  PROCESS REC <1>
.  WRITE <2>
.  END REC
END RETRIEVAL

This might be run with a parameter list such as:

(PARTS , PARTNUM PARTNAME PARTCOST)

The two parameters are separated by the comma. After text substitution has been performed, the program is:

RETRIEVAL
.  PROCESS REC PARTS
.  WRITE PARTNUM PARTNAME PARTCOST
.  END REC
END RETRIEVAL

Run time parameters can be specified:

On the RUN command
At the Args string when using the Run option from the member dialog.
On INCLUDE commands.

Just as with global variables, text parameter substitution happens at compile time. The NARG and SARG functions return the numeric or string parameters at run time.

INCLUDE BUFFER | FILE | MEMBER

INCLUDE BUFFER "buffer_name"          [ (parameter_list) ]
INCLUDE FILE { filename | attribute } [ (parameter_list) ]
INCLUDE MEMBER member                 [ (parameter_list) ]

Synonyms:

SET BUFFER "buffer_name"          [ (parameter_list) ]
SET FILE { filename | attribute } [ (parameter_list) ]
CALL member                       [ (parameter_list) ]

The INCLUDE commands include text from a buffer, file or member at the point of the command. Text inclusion commands can appear within any input source including included text.

Positional parameters specified on the INCLUDE applies only to the commands directly included by that command. If there are further text inclusion commands within an included set of text, then parameter numbers are reset. When a level is returned to from a deeper level, the calling parameters are once again in effect. The INCLUDE BUFFER command includes the text of the specified edit buffer at the point of the command. SET BUFFER is a synonym for INCLUDE BUFFER. Buffer names can be up to 32 characters and contain upper and lower case and special characters. If the buffer name is a name that follows the SIR name format (up to eight characters, starts with an alpha character, all upper case, no special characters), then quotes are unnecessary. If the name does not follow this format, enclose the name of the buffer in double quotation marks and ensure that upper or lower case letters are specified correctly.

The INCLUDE FILE command includes the text of the specified file at the point of the command. SET INPUT is a synonym for INCLUDE FILE.

Specify a full filename or attribute.

The INCLUDE MEMBER command includes the text of the specified file at the point of the command. CALL is a synonym for INCLUDE MEMBER. Specify the member to include. Only text members (with the :T suffix) can be referenced. Use INCLUDE MEMBER * in batch runs or at the front of a command set, to pass parameters to the commands that follow.

Specify a parameter list where required. Enclose the whole list in parentheses; separate individual parameters with commas. Note that blanks do not separate parameters.

Examples:

INCLUDE FILE 'C:\PROGS\WEEKLY.PQL'
INCLUDE FILE WAREHOUS.PQL (PARTS, PARTNUM PARTNAM PARTCOST)
INCLUDE BUFFER "Test Program"
INCLUDE BUFFER PARTS ( PARTS, PARTNUM PARTNAM PARTCOST)
INCLUDE MEMBER REPORTS.WEEKLY
CALL REPORTS.WEEKLY
CALL REPORTS.WAREHOUS ( PARTS, PARTNUM PARTNAM PARTCOST)

Assume a program, TEST1 is called. Any positional parameters in that program are referred to as <1>, <2>, etc. If this now calls a second program, TEST2, it also refers to any positional parameters as <1>, <2>. In the example, in TEST1, the positional parameter <1> is replaced with a "a"; in TEST2, the positional parameter <1> is replaced with a "c". For example:

INCLUDE MEMBER TEST1 (a,b)

TEST1:T
WRITE <1>
INCLUDE MEMBER TEST2 (c,d)

TEST2:T
WRITE <1>

FINISH

FINISH

Terminates processing of all input source commands and returns control to the current environment i.e. the operating system for batch runs or the menus.

If FINISH occurs in a set of either VisualPQL or Record Schema commands, the following actions are taken:

Within a ViusalPQL program, FINISH generates an END PROGRAM or END RETRIEVAL command, then executes the compiled VisualPQL program. At the end of VisualPQL execution, control is returned to the executing process, skipping any other commands in the input source(s).
Within a Record Schema command set (either RECORD SCHEMA or MODIFY SCHEMA), FINISH generates an END SCHEMA, then executes the schema definition. After the schema has been executed, control is returned to the executing process, skipping any other commands in the input source(s)

PEND

PEND

Terminates processing of commands in the input source where it appears and resumes execution in the calling input source. Execution resumes with the command immediately following the CALL or INCLUDE that initiated the processing of the procedure containing the PEND. If PEND is executed in the highest level input source, it is equivalent to FINISH.

If PEND is executed within either a VisualPQL or Record Schema definition, the following actions are taken:

Within a VisualPQL program, PEND generates an END PROGRAM or END RETRIEVAL command, then executes the compiled VisualPQL program. At the end of VisualPQL execution, control is returned to the calling level.
Within a Record Schema command set (either RECORD SCHEMA or MODIFY SCHEMA), PEND generates an END SCHEMA, then executes the schema definition. After the schema has been executed, control is returned to the calling process.

DO REPEAT

DO REPEAT repeat_symbol = parameter_list [ / ... ]
.
.  commands to be repeated with symbol value replacement
.
END REPEAT

The DO REPEAT command defines a block of text, usually commands, that is repeatedly copied as input. For each copy of the commands, substitution parameters are inserted into the block. For example, if a DO REPEAT contains ten lines of code and is repeated ten times, one hundred lines of code are generated. This command is not an alternative to one of the VisualPQL execution time commands such as the FOR command as it generates source code rather than looping at execution time.

A DO REPEAT block cannot be specified in another DO REPEAT.

The repeat symbol is a name of up to eight characters, beginning with a letter. The parameter list is composed of one or more parameters. Delimit parameters from each other with blanks or commas. The text within the DO REPEAT block is repeated once for each parameter in the list. The value of the parameter is substituted where the repeat symbol is found within the text. By default, the text of parameters is mapped to upper case.

For example:

PROGRAM
DO REPEAT REPSYMB = First Second Third
WRITE 'REPSYMB'
END REPEAT
END PROGRAM

The above text is expanded to be:

PROGRAM
WRITE 'FIRST'
WRITE 'SECOND'
WRITE 'THIRD'
END PROGRAM

Parameter values can be of arbitrary length. Delimit parameters that contain blanks, lower case values or other special characters with the dollar sign ($). For example:

PROGRAM
DO REPEAT REPSYMB = $FIRST Param$ $SECOND Param$ $THIRD Param$
WRITE 'REPSYMB'
END REPEAT
END PROGRAM

The above program is expanded to be:

PROGRAM
WRITE 'FIRST Param'
WRITE 'SECOND Param'
WRITE 'THIRD Param'
END  PROGRAM

TO Keyword

Parameter values can be specified with the TO keyword. When the parameter values end in numbers and the parameter to the left of the TO has a number of lower value than the parameter on the right, the list includes all the numbers implied in the range. For example:

PROGRAM
DO REPEAT X = PARAM1 TO PARAM5
WRITE 'X'
END REPEAT
END PROGRAM

The above program is expanded to be:

PROGRAM
WRITE 'PARAM1'
WRITE 'PARAM2'
WRITE 'PARAM3'
WRITE 'PARAM4'
WRITE 'PARAM5'
END PROGRAM

Parameters cannot have embedded numbers. The non-numeric part must be the same. For example the following are both invalid parameters:

DO REPEAT x = X12P1 to X12P2
DO REPEAT  x = X1 to Y3

Numeric constants can be used as parameters. For example:

PROGRAM
DO REPEAT X = 1 TO 3
COMPUTE NUM = X
WRITE NUM
END REPEAT
END PROGRAM

The above program is expanded to be:

PROGRAM
COMPUTE NUM = 1
WRITE NUM
COMPUTE NUM = 2
WRITE NUM
COMPUTE NUM = 3
WRITE NUM
END PROGRAM

Concatenation

DO REPEAT can be used to construct names by appending the text of the parameter to other text by specifying the repeat symbol preceded by an exclamation mark (!). For example, if the results of multiple tests are in variables called

MATH1 TO MATH5,
READ1 TO READ5

and AVG1 TO AVG5:

.  DO REPEAT X = 1 TO 5
.  WRITE 'Test Number X Scores: ' MATH!X READ!X AVG!X
.  END REPEAT

The repeat block expands to:

WRITE 'Test Number 1 Scores: ' MATH1 READ1 AVG1
WRITE 'Test Number 2 Scores: ' MATH2 READ2 AVG2
WRITE 'Test Number 3 Scores: ' MATH3 READ3 AVG3
WRITE 'Test Number 4 Scores: ' MATH4 READ4 AVG4
WRITE 'Test Number 5 Scores: ' MATH5 READ5 AVG5

Multiple Repeat Symbols

Multiple repeat symbols, each with its own parameter list can be specified. These specifications are delimited from each other with a slash (/). The lists should be of equal length and a warning is issued if unequal length lists are specified. When multiple repeat symbols are specified, the

DO
REPEAT

block is repeated once for every parameter in the longest parameter list, substituting the next parameter from each list in turn. When unequal length lists exist, the parameters of the shorter lists are cycled as often as is necessary to exhaust the longest list. The same result of the previous example can be achieved with the following code.

DO REPEAT X = 1 TO 5/  M = MATH1 TO MATH5/
          R = READ1 TO READ5/
          A = AVG1  TO AVG5
.  WRITE 'Test Number X Scores: ' M R A
END REPEAT

Other Examples

DO REPEAT is useful anytime a set of similar code must be generated repeatedly. Any command can appear within a

DO
REPEAT

block except for another DO REPEAT command.

Example 1. The following generates three different retrievals, each creating an SPSS file for the data in a different record type. Note that the repeat symbol RTNUM is used on the PROCESS REC statement and in the filename for the SPSS procedure command.

DO REPEAT RTNUM = 1 2 4
RETRIEVAL
.  PROCESS CASES
.    PROCESS REC RTNUM
.    GET VARS ALL
.    PERFORM PROCS
.    END REC
.  END CASE
SPSS SAVE FILE FILENAME = 'SPSS!RTNUM.SYS'
END RETRIEVAL
END REPEAT

Example 2. Consider a typical schema modification task in which many record types have the same variable with value labels. The following generates the value labels for a variable called MEDICINE in ten different record types:

DO REPEAT RTNUM = 1,4,7,8,9,13,14,15,20,22
MODIFY SCHEMA RTNUM
VALUE LABELS MEDICINE (1) 'Aspirin'       (2) 'Cough Syrup'
                      (3) 'Antihistamine' (4) 'Ointment'
END SCHEMA
END REPEAT

Example 3. Consider an application where many data files are created that have to be entered into the database with the ADD REC batch data input utility. The following set of commands reads in data from 27 files and writes out rejected records for each record type to a separate file:

DO REPEAT FILENUM = 1 TO 27
ADD REC INPUT = DATA!FILENUM.DAT /
        ERRFILE = ERR!FILENUM.LIS /
END REPEAT

CIF

CIF operator  [arg1, [arg2]]

The CIF command begins a block of commands to be processed only if the stated condition is met. The block of commands is terminated by the command CIF END.

The general structure of the CIF command and sub-commands is:

CIF operator [ argument1 [, argument2 ]]
.   Commands conditionally
processed
CIF TRUE
.   Commands processed if not in skipping mode
CIF FALSE
.   Commands processed if in skipping mode
CIF TF
. Commands processed under all conditions
CIF END

CIF blocks can be nested within one another. The arguments can only be constants (strings in quotes or numbers). Parameter and global variable substitution into the CIF commands is allowed.

The CIF command specifies an operator and zero, one or two arguments. The arguments are often values of global variables or of parameters on the RUN, CALL, INCLUDE FILE and INCLUDE BUFFER commands that are substituted in when the command is processed. The arguments can be strings in quotes or numbers. For the relational tests, arguments must both be of the same type.
(Note that the form of this logical condition is different from VisualPQL logical expressions.)
The operators are:

CIF EQ arg1 , arg2 arg1 is equal to arg2
CIF NE arg1 , arg2 arg1 is not equal to arg2
CIF LT arg1 , arg2 arg1 is less than arg2
CIF LE arg1 , arg2 arg1 is less than or equal to arg2
CIF GT arg1 , arg2 arg1 is greater than arg2
CIF GE arg1 , arg2 arg1 is greater than or equal to arg2
CIF B arg1 arg1 is blank, i.e. if no argument is specified
CIF NB arg1 arg1 is not blank, i.e. if an argument is specified
CIF DEF global_variable global variable is defined
CIF NDEF global_variable global variable is not defined

The B and NB conditions test whether the remainder of the command line is blank or not.

The DEF and NDEF conditions test whether the global variable name specified is currently defined.

Conditional blocks can be nested to any level, i.e. a conditional block can be contained within another conditional block. The inner conditional block is executed only if it is encountered while commands are not being skipped by any outer conditional block.

Each CIF conditional command must have a corresponding CIF END command.

Consider the following:

CIF EQ <1>,3
.
. commands
.
CIF END

If these commands are run with a parameter list of (5), the commands within the conditional block are skipped and not processed. If the parameter list is (3), the commands within the conditional block are processed.

CIF FALSE | TRUE | TF

CIF  FALSE
CIF  TRUE
CIF  TF

The CIF sub-conditional commands alter the effect of the previous CIF conditional. The sub-condition affects commands up to the next sub-condition or until the end of the block specified by the matching CIF END command. If a CIF conditional command is encountered while commands are being skipped, that entire block is skipped, up to and including its matching CIF END command.

CIF FALSE: Stops statement skipping if the last condition was false. If the last condition was true, skipping either starts or continues.
CIF TRUE: Stops statement skipping if the previous condition was true. If the previous condition was false, skipping either starts or continues.
CIF TF: Stops skipping. Statements following CIF TF are always processed.

CIF END

CIF END

Terminates a conditional block. If this command terminates a nested conditional block, the condition of the previous block is restored, i.e. proper nesting occurs.

CIF EQ 3,3                 CIF EQ 3,4
.                          .
.  (processed)             .  (skipped)
.                          .
CIF FALSE                  CIF FALSE
.                          .
.  (skipped)               . (processed)
.                          .
CIF EQ 1,1                 CIF EQ 1,2
.                          .
.  (skipped)               . (skipped)
.                          .
CIF END                    CIF END
.                          .
.  (skipped)               .  (processed)
.                          .
CIF END                    CIF END

Input Flow Control

As an alternative to the CIF block structures, there are a number of commands which give the ability to skip commands to a named point depending on conditions.

Seven commands test logical conditions relating to global variables and the existence of procedure families and members. Logical test commands specify the condition being tested and skip when the condition is true.

The general syntax of the commands is:

IFxxxxxx condition SKIP label

The commands are:

IFCOND(condition) SKIP label: Test a specified condition.
IFMEMBER [famname.]membname SKIP label: Tests for the existence of the named member and skips when the member exists. If the family name is not specified, the default family is used.
IFNOTMEMBER [famname.]membname SKIP label: Tests for the existence of the named member and skips when the member does not exist.
IFFAMILY famname SKIP label: Tests for the existence of the named family and skips when the family exists.
IFNOTFAMILY famname SKIP label: Tests for the existence of the named family and skips when the family does not exists.
IFGLOBAL global_varname SKIP label: Tests whether a global variable is initialized and executes the flow command when the global is initialized.
IFNOTGLOBAL global_varname SKIP label: Tests whether a global variable is initialized and executes the flow command when the global is not initialized.

The SKIP that follows a condition directs the flow of control to a named label. The name is used on the SKIP. Label a point in the input source by enclosing the name in braces {} starting in column one. Names begin with a letter and are from 1 to 8 characters with no special characters; labels are case insensitive, all labels are mapped to upper case.

There are three variant SKIP commands:

SKIPBACK

Looks for a label from the beginning of the input source. Execution continues with the line following the specified statement label.

SKIPFORWARD

Looks for a label from the current command. Execution continues with the line following the specified statement label. SKIP is a synonym.

SKIPRETURN

Returns to the calling procedure. One input source can INCLUDE another procedure. SKIPRETURN returns control back up a level.

If there is no label on the command, control is transferred to the first statement following the calling command in the calling procedure.

If a statement label is specified, control is transferred to the beginning of the calling procedure, statement skipping begins and execution continues with the first command following the specified label. This is equivalent to a SKIPRETURN and SKIPBACK. There is no direct SKIPRETURN and SKIPFORWARD.

Labels need not be unique. The first match found is used. There is one special label, the {*}. When looking for a named label, this special label matches anything.

IFCOND

IFCOND (logical_condition) SKIP label
Tests the specified logical condition and skips when the condition is true. The command must fit on a single physical line. The condition is specified within parentheses and may consist of:

global variables treated as string variables
string constants (enclosed in single quotation marks)
numeric constants
global variable text substitution specifications (e.g. <gvarname>)
parentheses
operators:
- string ( + )
- numeric (EQ =, LT <, GT >, LE <= , GE >=, NE ><)
- logical (AND, OR, XOR)
- unary (+, - , NOT)

The IFCOND command tests the value in a global variable. So global variables can either be used for text substitution by enclosing them in angle brackets, or referenced as string variables. If a global variable enclosed in angle brackets is found, the value of the global variable is substituted in the text. If a string, not in quotes, is found, it is treated as a global variable. All globals are string variables.

To use globals to set numeric values, the global name must be enclosed in angle brackets. To use a global which contains a string value, either specify the name of the variable, without angle brackets or quotes, or specify quotes around the angle brackets.

IFCOND (gvar = 1) Mixed mode error since gvar is taken as a string
IFCOND (gvar = 'A') OK since gvar is a string
IFCOND (<gvar> = 1) Works if a numeric value assigned to gvar. Gives 'Unknown global' error, if an unquoted string is assigned to gvar.
IFCOND ('<gvar>' = 'A') OK since a string is being compared to a string.

For example:

IF (<gvar> EQ 1) SKIPBACK TOP
IF ('<gvar>' EQ 'A') SKIPBACK TOP
IF (GVAR EQ 'A' ) SKIPBACK TOP

EJECT

EJECT [ ODD | EVEN ]

Causes the output listing in batch to skip to a new page. The EJECT command is not listed.

ODD: Causes the listing to continue on the next odd numbered page.
EVEN: Causes the listing to continue on the next even numbered page.

ERROR LIMIT

ERROR LIMIT { number | NONE }

Specifies the maximum number of error messages that are written for a given task such as a Record Schema definition or VisualPQL program. Once the limit is reached, no more messages are printed. Syntax checking continues and the summary of error messages lists all errors encountered, including those detected after the limit was reached. The keyword NONE suppresses all error messages.

A task is defined by TASK NAME commands. If no tasks are defined, the whole session is a single task.

PRINT BACK

PRINT BACK [ ON | OFF ] [ SAVE | RESTORE]
 [ [NO]CALL     ]
 [ [NO]COMMANDS ]
 [ [NO]FORMAT   ]
 [     MESSAGES n1, n2, . . .]
 [ [NO]REMARK   ]
 [ [NO]REPEAT   ]
 [ [NO]SKIPPED  ]
 [ [NO]TASK     ]
 [ [NO]USER     ]

Controls the listing of procedure commands, remarks and error messages in the output file or on the screen.

PRINT
BACK

can be used anywhere in a set of commands.

ON or OFF

SPACE

SPACE number

Generates the specified number of blank lines in the output listing.

STRING LENGTH

STRING LENGTH num

Sets the default length of implicitly declared string variables in VisualPQL or in the Record Schema. This is also the default length used for explicitly declared string variables for which a length is not specified.

WARNING LIMIT

WARNING LIMIT { number | NONE }

Specifies the maximum number of warning messages written to the output file for a given task. Once the limit is reached, no more warning messages are printed. Syntax checking continues and the summary of warning messages lists all warnings encountered, including those detected after the limit was reached.

The keyword NONE suppresses all warning messages.

A task is defined by TASK NAME commands. If no tasks are defined, the whole session is a single task.

Commands

This section describes commands that are not generic and can only be used outside VisualPQL programs or schema compilation in a similar way to running database utilities or batch data entry utilities. Commands are:

There are also a set of commands to manage members in a procedure file.

Note. Commands which are not valid VisualPQL are flagged as errors. RUN NAME and TASK NAME are recognised by the VisualPQL compiler and treated as indicating the end of that program.

ATTRIBUTE

ATTRIBUTE attribute_name FILENAME = "file_name"

Defines a short name (up to eight characters with no special characters) that is equivalent to the specified external filename. The file name must be enclosed in quotes. The file name can be any valid operating system file name, including any path, subdirectory or device specifications.

Once defined, the short attribute name may be used anywhere that a filename can be specified.

SIR creates and uses an attribute for every filename that it uses. List the currently defined attributes from the Settings menu item. Define attributes with the ATTRIBUTE command, with the OPEN command in VisualPQL and from the Settings system menu.

COPY DIFFERENCE FILE

COPY DIFFERENCE FILE

If the session is connected to Master, requests that all databases connected at that time through that Master are written to disk so that updates are available for other processes.

PAGESIZE

PAGESIZE { lines_page | NOEJECT } , characters_line

Controls the size of the page if output is directed to an output listing file. The lines per page specification is the maximum number of printable lines on a page. The default is 60 lines per page including three lines at the top used for run and task headings. The NOEJECT keyword suppresses new page generation, i.e. the printing is continuous. The default characters per line is 121.

This has no effect on VisualPQL procedure output files which have their own PAGESIZE options.

PRINT FILE

PRINT FILE filename

Initiates the operating systems print routine for the named text file.

RUN MEMBER

RUN MEMBER membername:[E|T] (args)

Runs the named member with any specified positional parameters. Can be used to compile text (:T) members or execute saved (:E) executables.

If a member name without a suffix is RUN, and both a :T or :E version exist, the system determines which to run based on dates and times of last update.

RUN NAME

RUN NAME text

Sets a main title for the output listing. Ends VisualPQL or schema processing. Has no effect on error or warning counts.

SCREEN OFF

The SCREEN OFF command closes the Execution Window explicitly during a command stream. This command is typically used after a full screen program when the execution window is no longer required but there are further procedures. The execution window is automatically closed at the end of a command stream.

SET

There are a number of system settings and parameters which can be set by command. The SET command sets the parameter to a particular value specified on the command.

The CLEAR command can be used with some parameters to reset back to the default.

The following parameters can be used:

CENY yyyy

SHUTDOWN MASTER

SHUTDOWN MASTER [NOLOGONS] [password]

If the session is connected to Master, requests that Master to shutdown.

The keyword NOLOGONS specifies that the Master should not accept any more client logons and should warn existing clients that the shutdown is in progress. Master only completes the shutdown when there are no clients connected.

If Master was started with a password, specify the password on this command.

TASK NAME

TASK NAME text

Indicates the end of one task and the start of a new task. This ends any VisualPQL compilation or schema definition.

Can define a subheading printed below the main heading at the top of each page of the print back listing. TASK NAME can be specified as often as needed.

Procedure File Commands

There are a number of commands that can be used to manage a procedure file. Commands are:

Creating

You can create procedure files that are available for generic use and not part of a particular database. Create a procedure file by creating a new database and renaming the procedure file from the initial dbname.sr4 to any valid filename.

Procedure files may be protected by access restrictions defined at the operating system level. Users of an alternate procedure file must have operating system read access and may be allowed write access.

Deleting

The procedure file is normally deleted along with the rest of the database files when the database is purged (deleted). When the

Delete
Database

option is used from the Database- Recover menu, the procedure file can be deleted or can be left intact. If a database is reloaded and the procedure file already exists, the existing procedure file is used and any reloading of procedures is skipped. If a database is imported and the procedure file already exists, the existing procedure file is used and any imported procedures are added to it. If they have the same name as existing procedures, you are prompted as to whether to replace the existing with the import.

Procedure References

Numerous commands reference members. A member can be uniquely referenced by its procedure file, family, member name and member type and both the family and member may be followed by a password. The various elements only have to be specified where used. For example, if the member does not have a password, it is not necessary to specify a blank password.

When specifying names with multiple elements, delimit the procedure file, family and member by full stops. Delimit passwords by a slash. For example:

CALL SYSPROC.PQL/FAMPASS.PROG1/MEMPASS:T

SYSPROC is the procedure file, PQL is the family with FAMPASS as the family password and PROG1 is the member name with MEMPASS as the member password. The :T indicates that this is a text member.

If PROG1 has no passwords and is in the default procedure file, specify the following:

CALL VisualPQL.PROG1

There is a default family which is used if no family name is explicitly mentioned when referencing members. The initial default family is the SYSTEM family. After a member is accessed, the family of the last accessed member becomes the default family. The default family may be explicitly set with the SET FAMILY command.

The SYSTEM Family

There is a special family that, in addition to other members, may contain login scripts.

CONDENSE

CONDENSE

Condenses the procedure file removing unused space.

Use this command on a regular basis, especially after many members have been updated.

Copies all members in the procedure file to a temporary scratch file and then rebuilds a condensed procedure file.

CREATE FAMILY

CREATE FAMILY fname [ /password ]

Creates a family on the procedure file. A family is a group of members.

Specify a password if required.

DELETE FAMILY

DELETE FAMILY [ fname, fname, ... ]  [ /NOINFORM ]  [ /OK ]

Prompts for permission, then deletes specified families.

All members in the family are purged. This is a DBA-only command.

NOINFORM: Suppresses informative messages for each family purged.
OK: Suppresses the OK prompt for permission to purge the family.

DELETE MEMBER

DELETE MEMBER membername,... [/DBA ]  [/NOINFORM ] [/OK ]

Deletes the specified member(s).

DBA: Deletes a member without requiring the member password. DBA security is required to do this.
NOINFORM: Suppresses message that member has been purged.
OK: Deletes without requesting confirmation.

PLIST

PLIST fileid [ namelist | ALL ]
             [ FAMILY | MEMBER ]
             [ [NO]INFORM ]
             [ [UN]NUMBERED ]
             [ [NO]RULER ]
             [ MIXEDCAS | UPPER ]

Writes a member to an external file in a suitable format for printing (with headers, paging, etc.).

namelist | ALL>: A list of members or families to list. ALL lists all members and is the default if a list is not specified.
FAMILY | MEMBER: FAMILY specifies that the namelist is a list of families. MEMBER specifies that the namelist is a list of members and is the default.
[NO]RULER: Specifies whether a ruler is displayed before the first line is listed. NORULER is the default.
UNNUMBERED: Specifies whether the lines are numbered. NUMBERED is the default.
MIXEDCAS | UPPER: MIXEDCAS specifies that listing is in mixed lower and upper case. This is the default. UPPER specifies that the listing is in uppercase.
[NO]INFORM: Specifies whether the number of lines listed is reported. INFORM is the default when listing to an external file. NOINFORM is the default when listing to the screen.

PREAD

PREAD fileid  [/CONFIRM]
              [/NOINFORM]
              [/PUBLIC]
              [/REPLACE]
              [/REPORT]

Reads the contents of the specified file and saves the contents as members in the procedure file.

A message is displayed for each member. If the new member has the same name as a current member, a prompt is issued for permission to replace the current member.

The disk file must be in the correct format for a PREAD which is produced by PWRITE. The file can contain many members, and each member must have the following format:

PROCEDURE  family.member
.      text of procedure
END PROCEDURE

CONFIRM: Prompts to confirm the addition of any member.
NOINFORM: Suppresses the display of informative messages for each member read. Sets the REPORT keyword.
PUBLIC: Saves members as PUBLIC.
REPLACE: Suppresses the confirmation prompt when replacing existing members of the same name. When REPLACE is not specified, a prompt is issued for permission to replace the member.
REPORT: Gives the total number of added/replaced members after the entire file has been read. This is set on if NOINFORM is specified.

PROCEDURE command

PROCEDURE  [family[/password].]member[/password]
   [REPLACE] [PUBLIC]
.
.   text of member to be stored
.
END PROCEDURE

The text in the PROCEDURE block is saved in the named member. if this command appears in the input it saves a member and can be used to save a member during a batch run.

These commands can appear anywhere. If a PROCEDURE command appears within a VisualPQL program or Record Schema definition set, compilation is suspended until the END PROCEDURE command is encountered, upon which compilation is resumed.

REPLACE: Allows an existing member of the same name to be overwritten (replaced). The default is not to replace an existing member.
PUBLIC: If the family or member is protected by passwords, PUBLIC allows all users to execute the member but not to read or modify it.

PWRITE

PWRITE fileid  [ mlist ]  [ /FAMILY ]  [ /NOINFORM ]

Writes the specified member(s) to the named file. If no members are specified, writes the entire Procedure File.

FAMILY: Specifies that the list is a list of family names and that all members of the specified families are written to the fileid.
NOINFORM: NOINFORM suppresses the listing of members written to the file. INFORM is the default.

RENAME

RENAME [ [family.][member1] [family.][ member2 ] [/[NO]PUBLIC]

Renames member1 to member2. Member1 no longer exists in the procedure file. If only member1 is specified, the member name is retained and only the options specified are changed.

[NO]PUBLIC: PUBLIC allows people to run a member without knowledge of the member password.