The procedural REXX language was developed by Michael F. Cowlishaw of IBM, UK and has been adopted as the Systems Application Architecture (SAA) standard. Initially available under IBM's VM operating system, it is now widely utilized across multiple platforms such as MVS/TSO, UNIX, MS-DOS, VAX, OS/2, and OS/400.
Distinguishing itself by its speed of development and ease of operation, REXX has become the standard procedural language, and was designed with the following concepts in mind:
Dealing with Reality Dynamic Scoping Emphasis on Symbolic Manipulation Keeping the Language Small Natural Data Typing No Defined Size or Shape Limits Nothing to Declare Readability Syntactic Units System Independence
There are no absolute data addresses. Instructions are only affected by what has already happened in the program and not what code lies hundreds of lines above or below. This makes a program easier to follow since there may be cases where massive printouts are not accessible.
Because of dynamic scoping there is no GOTO instruction because labels do not have fixed addresses within a routine.
From the user's perspective, all values in REXX are character strings. This data should be easy to manipulate with a text editor. This is why there is a wide selection of character manipulation functions and operators.
backwardstring = REVERSE ('ABC')
/* result is "CBA" in backwardstring */
Concatenation (placing characters next to each other) has special ease with REXX via the blank operator that concatenates strings with a space character in between. For instance:
SAY 5*100/20'%' OF CAPACITY
25% OF CAPACITY
A blank causes continuation for the SAY, not the termination of it.
Data has meaning that is totally dependent on how it is used. A variable can be used for holding either character or numeric data at any time. Since all data is kept as character strings anyway, REXX converts a numeric string to a number if it needs to.
A person must be able to read the program almost as if it were written in plain English. The tokens can be created in such a manner as to be both easily unique and adequately descriptive. The program is to be easy to read, follow, and (therefore) debug.
Some significant criteria are:Upper and lower case alphabet support.Almost free format spacing between tokens for easy reading.Punctuation marks are used only to prevent vagueness.Current concepts of structuring are easily implemented in REXX.
Binding between line ends and code is relaxed enough to allow flexibility in coding so that several clauses can be written on one line or spread between several lines to allow heavy commenting.
/* several clauses on a single line below */
IF grass_length >= 6 THEN SAY "Mow the lawn" ELSE nop
/* several clauses, one clause per line, with commenting */
IF grass_length >= 6/* see if grass is 6 or more inches high */ THEN /* do this if grass is that high */
SAY "Mow the lawn"/* Display this message */ELSE/* but if grass is shorter than 6 inches */ NOP/* execute No OPeration instruction to complete the IF construct */
Note the use of the NOP instruction above. This instruction literally does nothing except exist as a legitimate command. Its use is to provide something to be done after the THEN OR ELSE sub-keywords especially when several nested IF instructions exist.
The clause is the basic syntactic unit in REXX. It is terminated by a semicolon. Several clauses may be on the same line as long as they are separated by semicolons. A semicolon is not necessary at the end of a line.
The short size of the syntactic units allows for easier diagnostics.
/* Three clauses on a line */DO ; SAY 'middle clause' ; END
/* Three clauses on three lines with implied semicolons at line end */DO /* 1st clause */ SAY 'middle clause'/* 2nd clause */END/* 3rd clause */
REXX was originally designed to be independent of hardware and systems. However, each implementation generates system dependent attributes so the program can interact with its environment. REXX has many powerful extensions that greatly enhance its utility and performance.
All programs are constructed from a series of one or more clauses. Each one is made up of zero or more leading spaces; a sequence of tokens (as described below); an optional number of trailing spaces; and the semicolon ( ; ) delimiter. The semicolon may be implied by some keywords, a colon, or just by end-of-line. Leading spaces and those prior to a delimiter are ignored by REXX.
/* this comment is a token */
/* the line below this comment is a clause containing 6 tokens */
SUM = 2 + 3 ;
/* here it is again with each token identified */ SUM(token1) =(token 2) 2(token3) +(token4) 3(token5) ;
REXX is made up of tokens (In programming languages, a single element of the language. For example, a token could be a keyword, an operator, or a punctuation mark.) that are either blanks or items of almost any length separated by spaces or their own nature as with comments. The tokens are:
Comments Implied Semicolons and Continuation Characters Literal Strings Numbers
A semicolon (;) is assumed to terminate each line unless the line is within a comment or the final (non-comment) token was a comma (,) which is treated as a continuation character. Otherwise, a semicolon may be used to separate clauses on one line.
/* examples of use of implied semicolon and continuation character */
SAY 'Hi there'
/* semicolon implied in line above */
/* in the instruction below, the only implied semicolon is after the last variable name because of the comma continuation characters */
SAY very_long_variable_name1 very_long_variable_name2 very_long_variable_name3 , very_long_variable_name4 very_long_variable_name5 very_long_variable_name6 , very_long_variable_name7
A string of any characters delimited by apostrophes(') or quotation marks ("). For use of either delimiter within a literal string, the other delimiter must be used. Two delimiters with nothing between is called a null string.
literally = "It's a good idea."null_string = ""
Most implementations should support 100 character long literal strings. In fact, REXX supports literal strings as great as the maximum size of a REXX program (over 64,000 bytes) but it is highly unlikely that anyone would use one that long. When a left parenthesis " ( " immediately follows the literal's delimiter, REXX will assume the literal is the name of a function.
These characters ; ) ( : , are significant when not used as part of a literal string.
x = 1 + 2 ; y = x + 3/* semicolon to separate assignment clauses */x = y * (x + 1)/* parentheses to affect calculation */my_subroutine:/* colon to identify a label for CALLing */COMPARE(x,y)/* comma to separate items in function call */x = part1 + part2 + ,part3 + part99/* comma as continuation character at line end *//* final part of continued line */
Symbols are alphanumeric character groups which may also include the ! $ ? . # _ @ characters. Symbols which start with a numeric character (0-9) and end with "e" or "E" may be concatenated with a sign and more digits to indicate exponentials.
KEYWORDS and VARIABLE NAMES also are considered symbols.
Before use, any lower case alpha characters are converted to upper unless they are part of a literal string.
An EXPRESSION has at least one term and usually includes OPERATORS. Most operators act on pairs of terms. Operators that are positioned between terms are dyadic, while one or more prefix operators act on the terms that immediately follow them. Terms may include function calls, sub-expressions, string literals, or symbols.
/* the line below is an example of the equal sign being used as a dyadic operator because it is BETWEEN two terms */
xyz = 100/* dyadic operator "=" in an assignment expression */
/* the lines below are examples of the minus sign begin used as a prefix operator because it affects the term immediately to its right */
x = 100 /* initialize a variable */
SAY -x+1/* prefix operator "-" to display "-99" expression */
SAY -LENGTH('abc')/* prefix operator "-" to display "-3" after a function call */
Strings may be concatenated with the || operator or by simply placing them next to each other without a separating blank (abuttal).
firstv = '2.00'/* assign string value to first variable */
weight = firstv||' pounds '/* concatenate first variable with string literal (including blanks) into the variable "weight" */
/* displays "2.00 pounds" */
SAY weight '$'firstv/* display the concatenated string in "weight", a dollar sign, and the first variable */
/* displays "2.00 pounds $2.00" */
Concatenation Summary Example:
alpha = 'a con'/* assign delimited literal to variable */beta = tinuous /* assign non-delimited literal to another variable after upper case evaluation */gamma = alpha||beta' string'/* concatenate 3 items into a variable */SAY gamma/* displays "a continous string" */SAY evaluates to upper/* displays "EVALUATES TO UPPER" */SAY stays in' lower'/* displays "STAYS IN lower" */
Case sensitive character comparisons are made unless BOTH terms are numeric. The string comparisons ignore trailing blanks (the shorter string is padded on the right) as well as leading blanks unless it is a strict comparison. Strict operators are created by doubling the normal operators. Normal and strict comparisons both return "1" to represent true and "0" for false .
/* Example of comparatives */
SAY (55 > 44)/* True: 55 is greater than 44 so a "1" is displayed */SAY ('AA'==' AA ')/* False: not strictly equal so a "0" is displayed */
Normal Comparative Summary Example:
" A " = "A" /* True ("1") result - blanks ignored */"044" > "33" /* True ("1") - can handle a leading zero */
Strict Comparative Summary Example:
" A " == "A" /* False ("0") - everything counts */"044" >> "33" /* False ("0") - zero is not strictly nothing */x = 3; x << 8/* True ("1") - value of "x" is less than "8"*/a \== "A"/* False ("0") - case conversion before comparison */
Boolean (& [AND] | [OR] && [XOR] \ [NOT]) logical comparisons have the same result values as the other comparisons.
SAY ((1 > 2) && (30 > 20))/* eXclusive OR will return a True ("1") result since only the second comparison is true */
Boolean (logical) Summary Example:
(5 > 1) & (0 < 9) /* AND: True ("1") since both true */(5 > 1) | (7 > 8)/* OR: True ("1") since at least one is true*/(9 > 0) && (0 = 0) /* XOR: False ("0") since both true */\ (0 > 1) /* NOT: True ("1") since 0 is less than 1, a logical negation of 0 is a "1" */
Labels are used for jumping within a REXX program. A label is a single symbol followed by a colon. Although a label is considered a clause, the semicolon is not required. Multiple labels may follow each other.
/* use of labels for a CALL */
CALL oak/* call a subroutine */CALL rose/* call another one */oak: /* single label */ SAY 'tree' /* execute instruction */ RETURN /* return to calling point in program */
aster: /* another label */
rose: /* label called in this example */
marigold: daisy: /* other labels which may be called */ SAY 'flower' /* execute instruction */ RETURN /* return to calling point */
A null clause is a comment or blanks. Not being an instruction, it cannot be used as a place holder or dummy instruction as NOP REXX (No OPeration) can.
/* This line is a null clause because it is a comment */
/* the line below has 3 clauses */x = '1st clause'; /* null 2nd clause */ ; y = '3rd clause'
/* comments around */ ; ; /* a blank clause */
/* two nulls around */ ; NOP ; /* an instruction clause */
Variables are objects whose values may be changed during a program by assignments of new values. The new value will be regarded as a character string and may contain any number of any characters. A symbol name may not begin with a period or a digit.
An assignment clause takes this form: symbol = expression [ ; ]
x = 0x = 2 + 2x = y + (7 * z)var_symbol.used_here#1 = !var_symbol2 = 456var_sym3 = "It's the first day of the process."
/* quotation marks here to delimit literal string with an apostrophe */
The PARSE instruction is also used for the assignment of values to variables.
When a symbol has not been assigned a value, its uninitialized value is the upper case value of the symbol itself.
/* neither symbol below has been previously defined */state = liquid/* variable "state" is assigned the character string "LIQUID" */
KEYWORDS and variable names are both considered symbols. Before use, any lower case alpha characters are converted to upper when they are keywords or variable names or non-delimited strings.
Constant Symbols Simple Symbols Compound Symbols Stems (as part of Compound Symbols)
Begin with any non-numeric symbol character(s) and do not contain any periods.
/* examples of legitimate symbol names */
MYWORK1/* correct - continuous alphanumeric word*/SUM_TOT/* correct - underscore may link words */$1ST_QTR93/* correct - dollar sign may start symbol name */@WORK/* correct - "at" sign may start symbol name */INBASKET!/* correct - exclamation mark may be in symbol name */
/* examples of illegal symbol names */
2ND_BASE/* wrong - starts with digit */
OFF-BASE/* wrong - contains the minus numeric operator */POP,FLY/* wrong - contains comma continuation character */HI;STYLE/* wrong - contains semicolon clause terminator character */UP FRONT/* wrong - contains embedded space and would be seen by REXX as two names */
A compound symbol has at least one period and one other character but does not begin with a period or numeric character. The part before the period is the stem and the rest (delimited by periods) is the tail.
D. QTR.A..FEB TABLE.ROW
Prior to use, the simple symbols in the tail are replaced by their assigned or uninitialized values and create a derived name. The use of a stem and tail allows for subscripted variables when the symbols share the same stem name.
/* example of the use of compound symbols */
x = 1/* assign "1" to the variable "x" */
table.x = 100/* 100 to derived "TABLE.1" */x = x + 1/* increment "x" by "1" so it's now "2" */table.x = 200/* 200 to derived "TABLE.2" */
/* now display the values contained in our variables */
SAY x/* displays "2" */SAY table.1/* displays "100" */SAY table.x
/* displays "200" */SAY table.z/* displays "Z" since "z" was never initialized, it becomes the upper case value of itself */
When a period is the last character, then it is still called a stem but can be assigned a value that applies to it even in compound symbols unless another assignment is made.
/* example of stem assignment */
tool. = 'metric'/* assign universal value to stem variable */tail = 2/* assign value to simple variable */tool.tail = 'shim'/* assign new value to derived "TOOL.2" */tool.99 = 'hammer'/* assign new value to derived "TOOL.99" */SAY tool./* displays "metric" - original assignment of stem */SAY tool.tail/* displays "shim" - same as "TOOL.2" */tail = 99/* assign new value to "tail" */
SAY tool.tail/* displays "hammer" - same as "TOOL.99" */SAY tool.kit/* displays "metric" since "kit" was never assigned a value */
You may enter the following commands in the command line of a SuperVision scrolling window. You may change the command prefix from a period (.) by clicking the Options button in SuperVision or by selecting Options from the SuperVision
File menu. If applicable, any numeric return code will be placed in the RC special variable. Sending a command to the environment takes the form of any valid expression.
This command allows a text message to be sent to a specified node, directly from the command line of a SuperVision scrolling window.
Syntax .MSG <host nodename> text_message or Msg(['Node'],'Host,'Msg')
Parameters Part Description
host The host window where the message is to be sentnodename The name of node where the message is to be senttext_message The message a user wishes to send
Example .msg <A sv4_node01> Welcome sv4 users!!!
We suggest all NEW programs use the following overhead-reducing advanced method and where possible, convert the standard method to the advanced:
This command is not case sensitive.
As long as a user is logged on to SuperVision, this command does not require the target addresses to be in the IP/Nodelist table of SuperVision. If they are, any extra information—such as the gateway address to use or an overriding User ID—will be used; otherwise, the address will be used "as is" with the currently logged-on User ID information.
Closes down the SuperVision program WITHOUT displaying a confirmation dialog. This command uses the menu item "Exit Immediately", found under the File drop-down menu, and the "SVMenu" function to activate it (see Built-In Functions for information on the SVMenu function).
Syntax .SHUTDOWN seconds
Parameters Part Description
seconds number of seconds until shutdown begins
Notes: This command is not case sensitive.
You can cancel this command by entering ".shutdown abort" in the command line.
A computer language uses words that have special meanings within that language. These are called KEYWORDS. These words may vary from language to language and yet do the same thing. For example, the GOSUB keyword in BASIC and the CALL keyword in REXX all are used to temporarily transfer control to a subroutine whose label immediately follows that keyword.
In REXX, one or more clauses beginning with a keyword constitute an instruction. If the clause does not begin with a keyword, then it is not recognized as an instruction. If the second token is not an equal sign (denoting assignment) or a colon (denoting a jump point label), then the instruction is recognized by REXX.
Note: Certain keywords necessitate sub-keywords later in the clause, and items within brackets ( [ ] ) represent options.
When the logical OR symbol ( | ) is used, it represents a choice of subkeywords or options of which only one may be used.
IF a=0 THEN shipping = 'ground' /* keyword with condition followed by a subkeyword and an assignment */
CALL name [expression]; The DO Instruction DROP GLOBALS [ HOST | NODE ] ; DROP varnames;
EXIT [expression]; EXTRACT keyword [optional parameter]; FLUSH GLOBAL [NODE | HOST] name [name...] IF Logical Expression INTERPRET [expression]; ITERATE ; LEAVE ; NOP ; PARSE
CALL causes the named routine to begin execution. It may be an external routine , an internal routine, or another program. After execution of the called routine, control is returned to that line. In the case of internal routines, previously existing variables are accessible by the called routine.
Routines may also be nested up to 100 levels. Only one argument (up to 255 characters long) may be passed via the expression.
An internal routine may also create and use local variables, but then it cannot use variables with the same names from the calling routine. Variables that are to be shared with internal routines should be declared with the GLOBAL instruction. If an internal routine is called, it should normally terminate with the return instruction.
The use of call will not affect the status of a DO loop unless the loop control variable has been deliberately altered within the subroutine.
/* use of CALL to internal routine */
GLOBAL long wide/* declare variables for host (default) */long=10; wide=15/* initialize */CALL area. . . area:SAY 'The area is: ' long * wide /* displays "The area is: 150" in this case */RETURN
In the example below, we are CALLing another REXX program as a macro. We are using a string in our expression. We can send the string as a literal or we can use a variable to hold the string value as long as the final form of the expression being included in our CALL evaluates to no more than 255 characters in width.
This allows an entire list of variables to be eliminated. 'DROP GLOBALS HOST' eliminates all globals scoped to the current host, without touching any other variables. 'DROP GLOBALS NODE' eliminates all machine-wide (i.e., node) globals, without touching the host-scoped globals or the local symbols.
If neither HOST nor NODE is specified, 'DROP GLOBALS' defaults to 'DROP GLOBALS HOST'. (See the GLOBAL [NODE | HOST] name [name . . .] instruction] for more information on the different types of symbols/variables supported by REXX.)
This instruction de-assigns variables. Varnames is a series of space delimited variable names. This command will apply to all variables (see the GLOBAL [NODE | HOST] name [name . . .] instruction) that share the same name. They are returned to their uninitialized state regardless of any previous assignments. This even applies to stems and values assigned to them.
/* assign values to 3 local variables */
x=4park. = 'greenspace'park.bench = 'concrete'SAY park. park.bench x/* Display is "greenspace concrete 4" */DROP park. x /* all above variables now GONE */SAY park.bench x park. /* Display is "PARK.BENCH X PARK" - the uninitialized forms of all 3 variables */
Returns various data by creating local variables and assigning values to them. Note that if a variable of higher precedence (a node or host global) with the same name already exists, it will be used rather than creating a local with the same name.
The compound variables created have the same base (stem) name as the EXTRACT subkeyword, and a numeric extension: NODENAME.0, NODENAME.1, etc. The .0 variable contains the number of variables in that series created by EXTRACT, not counting the .0 variable itself. The .1, .2, and higher variables contain the actual extracted information. This is done so that an EXTRACT can create a list of items, which can then be examined in sequence using a DO loop .
CONNECT.0 = 1CONNECT.1 = <connect string> contains text indicating the type of connection to the scrolling (host) window in which the REXX program is running. The connection will be either local to a mainframe or remote to another SuperVision workstation (in which case the text will include "at" followed by the nodename). Returns "none" if a connection does not exist.
Returns information about which keygroups are active, and what they are called, for any given window. Where hostid is "S", "A – P" or "*". Displays for each of 16 available keygroups:
1. keygroup file name (KeyGrpNN.ini, where "NN" ranges from "01" to "16") or "UNDEFINED" if not yet created2. "0" meaning inactive, or "1" indicating active 3. name assigned to the keygroup (if available; i.e. SOFTDUMP)
KEYGROUPS.0 = 16KEYGROUPS.1 = Gives information regarding keygroup 1KEYGROUPS.n = Gives information regarding keygroup n
If " * ", the extract returns information for the scrolling (host) window in which the REXX program is running.
Note: The following is applicable to NETBIOS CONNECTIONS ONLY.
A functional console is a workstation which is displaying what is also seen on the main console of the system. There may be several functional (or "Remote") consoles in operation.
"Connect info" is specified as a string of the form "xx hhhhhhhhhhhh", where the h's represent the 12-digit unique ID of the connected node, and xx is the two-character ID for the host on that node which is making the connection. The string will be null if no connection is made (i.e., NETCONNECTS.1 will be a null string if Host A has no remote console #1 connected).
NETCONNECTS.0 = 0 if nodename not found, 20 if nodename foundNETCONNECTS.1 = Connect info for Host A's functional console.NETCONNECTS.2 = Connect info for Host A's Remote1 console.NETCONNECTS.5 = Connect info for Host A's Remote4 console.NETCONNECTS.6 = Connect info for Host B's functional console.NETCONNECTS.10 = Connect info for Host B's Remote4 console.NETCONNECTS.20 = Connect info for Host D's Remote4 console.
Note: The following is applicable to NETBIOS CONNECTIONS ONLY.
Gets the HOSTNAMEs of the workstation with the given ‘nodename’.
NETHOSTS.0 = 4 if <nodename> found, 0 if not foundNETHOSTS.1 = <name of host A at named node>NETHOSTS.2 = <name of host B at named node>NETHOSTS.3 = <name of host C at named node>NETHOSTS.4 = <name of host D at named node>
Note: The following is applicable to NETBIOS CONNECTIONS ONLY. NODEID.0 = 1NODEID.1 = the 12 hexadecimal digit ID for the network adapter hardware that is installed within the current workstation (the "unique ID" for this network node, same as the LAN adapter's Burned-In Address).
This is a command that can be executed from within a REXX program. When executed, all unread messages are purged. The next "PARSE MSG" instruction will receive the next message that arrives following the "FLUSH" command.
Creates global variables and moves variables between the several variable lists maintained by REXX. The default list is HOST. These variable lists are as follows:
Node GlobalVariables are visible to any program running on the current network node (workstation). Each workstation has its own list.
Host GlobalVariables are visible to any program running on the current host, but not on any other host. Each host window has its own list.
LocalVariables are visible only to the current REXX program.
To summarize, system will always maintain these lists of variable names in a hierarchy of visibility:
Node Global list: The highest level. This list only exists for one workstation.Host Global list: This list only exists within one window.Local list: This list only exists while a program is running.
Processing hierarchy When a variable is used, the lists are searched in the following order for that variable: Node Globals, Host Globals, and Locals. Thus, if another macro creates a Host Global named "X", subsequent variable accesses to "X" will find that Host Global and not a local variable of the same name. The same is true of variables with higher precedence.
If, neither NODE, nor HOST is specified, then HOST is assumed. Note that multiple variables can be specified, but NODE or HOST can only be specified at the start of the instruction. If the named variable does not exist, it is created as an uninitialized variable (equal to its own name).
If a local variable is moved to any of the three global lists, it ceases to exist on the local list and can never be moved back to the local list. Once a HOST or NODE variable is declared, it can be moved between the HOST and NODE lists at will.
/* example of GLOBAL use */
var1 = 1 ; var2 = 2 ; var3 = 3 /* create and initialize 3 local variables */GLOBAL NODE var1/* move "var1" to NODE list */GLOBAL var2/* move "var2" to default HOST list */SAY var1 var2 var3/* displays "1 2 3" */DROP GLOBALS HOST/* drop all host globals */DROP GLOBALS NODE/* drop all node globals */SAY var1 var2 var3/* displays "VAR1 VAR2 3" */
Syntax: IF Logical_Expression[;]THEN[;]instruction [ELSE[;]instruction]
The standard conditional branch which executes any instruction(s) after the sub-keyword THEN when the valid logical expression evaluates to a "1". But if it evaluates to a "0", then it will execute any instruction(s) after the optional ELSE. Care should be taken since the ELSE will link with the nearest IF regardless of any text indentation hence the importance of the NOP instruction.
/* Example of IF use */
IF state = 'Maine' THEN ; IF city = 'Augusta'
/* nested IF */ SAY "Capital!"
ELSE ; NOP /* force termination of nested IF */ ELSE ; SAY "Not the state of Maine"
Without the forced termination, the final line would link itself to IF city = 'Augusta'. The IF instruction can also set off a DO instruction so groups of instructions can be executed if a condition is true.
/* Example of IF used with DO */
IF city = 'Paris'/* begin outer IF */ THEN DO/* begin DO */ SAY 'The selected city is Paris'/* show the town */
IF land = 'France' THEN/* inner IF */ SAY 'Bon jour. There is a Paris in France.' ELSE ; NOP/* end inner IF */
IF land = 'Texas' THEN/* inner IF */ SAY 'Howdy. There is a Paris in Texas.' ELSE ; NOP/* end inner IF */ END /* end the DO */
ELSE ; SAY 'Not the correct city name'/* end outer IF */
This instruction will send control to the END of a DO loop .
i =0/* initialize a loop variable */DO WHILE i <= 5/* set a condition */ i = i +1/* increment variable */ IF i = 3 ;/* check for value of 3 */ THEN ITERATE/* head for end */ SAY i/* display loop variable */ END/* bottom of construct */
This instruction does nothing. Its primary utility is in the construction of IF...THEN...ELSE clauses by providing a valid instruction for execution after ELSE. Therefore, any further ELSEs will not bind to the wrong IF.
PARSE [UPPER] HISTORYPARSE [UPPER] [WAIT|NOWAIT] MSG [template]PARSE [UPPER] SOURCE [template]PARSE [UPPER] VALUE [expression] WITH [template]PARSE [UPPER] VAR name [template] PARSE [UPPER] VERSION [template]
The template is a series of symbols separated by spaces and/or patterns. This instruction assigns data to variable(s) according to the rules on parsing. The rules on parsing are thoroughly covered in the PARSING FOR ARG AND PARSE.
The UPPER option causes all characters to be converted to upper case before parsing.
No variables are set if no template is provided however other actions prepare the data for parsing later. PARSE VALUE will have the expression evaluated, and for PARSE VAR, the variable name will be examined to make sure it has been initialized to a value.
Forms of PARSE use data as follows:
PARSE ARG PARSE HISTORY PARSE MSG PARSE SOURCE PARSE VALUE PARSE VAR name PARSE VERSION
Retrieves previous messages, processing backward through the current log.
Each invocation of the "PARSE [UPPER] HISTORY" command will retrieve the previous message to the last one retrieved. To enable programs to more easily keep track of how far back in the log they have travelled, the SV timestamp is set at the front of each message in the format "HH:MM:SS", always precisely nine (9) characters.
Allows a REXX program to access its host console stream, one message at a time. If no messages are waiting to be accessed, PARSE MSG will either:
1. pause up to 5 seconds, if the WAIT modifier is active (the default). If a message is received during that time, it will be used as the value to parse; otherwise, a null string (") will be used.2. immediately use the null string (") as the value to parse, if the NOWAIT modifier is active.
/*example of getting a message to parse*/
'.ZDSYS'/*cause system to generate status message*/PARSE MSG my_status/*send entire message string to one variable*/SAY my_status/*have REXX display the message*/
The example will display something like:
"M7 DSYS001I 08.52.44 SUBSYSTEM M7 IS IN NORM STATE".
Causes the list of current global and local variables to be dumped into the REXX Tracing window, which you can access by holding down the Ctrl key and pressing the F11 key. No parameters are required. The dumped information has the format:
<var type>: <name>=<value>
where <var type> is either "Local", "HostGbl", or "NodeGbl".
WHEN "search_string" THEN... [WHEN "another_search_string" THEN ...] [WHEN TIME THEN...]
[WHEN COUNT THEN...] END
The REXX extension allows the operator to conduct an exhaustive search of incoming console messages for a specific case sensitive character string. It is to be used in combination with the PARSE MSG instruction to allow an operator to seek and view a particular message or message type from the host.
The operator may specify the maximum number of seconds (max_secs) to conduct the search for before automatically terminating the search process. The highest value allowed is 86400 (one day). If no maximum is specified, then it defaults to zero and there is no time limit on the search.
The operator may also specify the maximum number of messages to search through before automatically terminating the search. The minimum value is zero (no limit), the default value is one message, and the maximum is 4294967295 (over 4 billion).
Both maximum time and maximum messages may be specified.
The WHEN TIME and WHEN COUNT options allow the inclusion of an action (such as a SAY instruction or a DO construct) if either the time limit has elapsed or the message count has been reached.
If the search string is found, the next PARSE MSG instruction will access the host message containing the search string. If it is not found, then PARSE MSG will access the message immediately following the last message SEARCH had examined.
/* search for a special word for 20 seconds or 100 messages*/
SEARCH TIME 20 COUNT 100 WHEN 'pool' THEN DO/*see if any messages on memory*/ PARSE MSG found_it/*get the entire message string into a variable */
SAY 'string found' SAY found_it/*display entire message*/ END/*done - go to instruction end*/ WHEN TIME THEN SAY 'we ran out of time'/*time limit reached*/ WHEN COUNT THEN/*message count reached*/ SAY 'we looked at enough messages' END
The REXX equivalent of the CASE . . . OTHERWISE . . . ENDCASE construct in pseudocode. It presents a set of alternative action sets. The first that evaluates True is executed and the rest are skipped. If none are True, then the OTHERWISE is executed. If it is possible for no WHEN clauses to evaluate as True, then an OTHERWISE should be included as good programming practice.
The whenlist syntax is:
WHEN logical_expression [;] THEN [;] instruction [;]
The example below shows a simple example of the SELECT construct with all the whenlist items on individual lines.
/* SELECT construct example #1 */color='purple'/* assign a value to variable for evaluation */
WHEN color = 'red' THEN SAY 'primary color'
WHEN color = 'purple' THEN SAY 'combination color'
WHEN color = 'plaid' THEN SAY 'color pattern'
WHEN color = 'white' THEN SAY 'absence of coloring'
OTHERWISE SAY 'no valid color selection'
In the above example (#1), the first WHEN clause evaluates as False (since color is not "red") so the sub-keyword THEN and its clause are not executed. Evaluation proceeds to the next WHEN. The second WHEN clause evaluates as True (since color is "purple") so the rest of that line is executed.
Because a WHEN clause in this construct has evaluated as True, the third and fourth WHEN clauses are skipped and the OTHERWISE is also skipped.
The next example (#2) is a bit more complex. It shows how a DO construct can be set off by a True condition at a WHEN. The ellipsis (. . .) represents an indefinite number of statements which may be included within an executed DO construct. It also shows how the whenlist item can be spread among two or three lines for the sake of readability.
This is another example of how indentation can be used to help the programmer follow the logic of a program and ease the process of modification or debugging.
/* SELECT construct example #2 */
option = 0/* set an option value for this example */SELECT
WHEN option = 1 THEN DO/* all of item on one line */ . . . END
WHEN option = 2 THEN/* item spread across two lines */ DO . . . END
WHEN option = 3/* item spread across three lines */ THEN DO . . . END OTHERWISE DO SAY 'No valid option found'
SAY 'Please try again' END END
In this example (#2), the OTHERWISE will execute because none of the WHEN clauses evaluated as true.
Controls the generation of tracing information sent to the scrolling (host) window. The following TRACE options are supported:
I - Intermediate values. Traces any variable assignments made via either an assignment statement or the PARSE instruction, at the time they are made. Also traces the result of each expression evaluation, including expressions nested within other expressions (i.e., expressions in function-call parameters).
S - Trace Source lines before execution
X - trace eXpression results, including expressions nested within other expressions (i.e., expressions in function-call parameters).
A - All of the above
O - tracing Off (none of the above) By default, tracing is off.
Options may be combined (e.g., "TRACE 'XI'"). Note that the 'S' option implemented by our system is not the 'S' option described by Cowlishaw.
TRACE x/* let's just show the results of expressions this time */
Function_name is a either a symbol or a literal string which is regarded as a constant. The comma-separated expressions are known as the arguments to the function. Each one may include function calls of its own.
It is critical to remember that a function name MUST have a left parenthesis abutting the last character of the name. If there is any space between them, it will not be recognized as a function. Also, most functions produce a return value and it is best to use a variable to receive that value or the value will be passed to the host.
good_function(ok) /* correct syntax for function call*/ fail_function (bug) /* wrong way, has embedded space */ w_count = WORDS ('returns a number')/* this one will return a "3" in "w_count" */
All built-in functions are a part of the REXX language. They may be invoked at any time.
REXX will report any syntax errors found in either the function or the function call.
Sends a message to a user message sub-window or to the SuperVision Alert Manager window.
This function only applies to SuperVision.
- category is the message type: ‘Attn’, ‘Warn’, ‘Prio’, or ‘0’ through ‘9’, indicating to which keyword group this message should apply. Use SuperVision’s Automation Rules Editor (Keygroup Editor) to set the desired value.
- msg is the message text that you want to display.
- color is the name of a color that overrides the default setting.
If category is ‘0’ through ‘9’ and color is ‘*’, the default color for the appropriate user message window will be used.
Instead of ‘Attn’, ‘Warn’, or ‘Prio’, you may use ‘A’ or ‘a’, ‘W’ or ‘w’, ‘P’ or ‘p’, respectively.
/* Example */X=Alert('A','Attention required', 'red')
Returns string or data about argument string(s). The number of blank delimited words is returned when there are no parameters. The nth argument string is returned when only n (negatives prohibited) is used. A null string may be returned.
The option checks for the explicit omission or existence of the nth argument string.
/* After a " CALL name 'abc def xzy' "the Arg() function will return the values in the following manner */
Arg() == 3 /* it says there are three space delimited strings */Arg(1) == 'abc'/* it returns the 1st string */Arg(4,'o') == 1 /* It returns a "True" because there is no 4th string (omitted) */
[WinNT ONLY – Win9x always returns zero] The AdminDriverAdd function is used to install a new service onto the system.
Service //The driver name to addDisplayName // The driver name as presented to usersImagePath // The pathname to the driverMsgName //The event viewer msg source name (optional)MsgFamily // The event viewer family (optional)MsgPath //The event viewer msg pathname (optional)
Startup //The driver startup mode)
Driver The name of the driver to install, i.e. “TKRNG864”.DisplayName The driver name as presented to users, i.e. “Token-Ring Model 864”.ImagePath The pathname to the driver, i.e. “%SystemRoot%\System32\TKRN864.SYS”MsgName If this driver has a message file then this should be the appropriate event viewer message source name, typically the same as the driver name. If there is no message file then leave this parameter empty along with the MsgFamily and MsgPath parameters.
If this driver has a message file then this should be the appropriate event viewer family: “Application”, “Security” or “System”, otherwise leave this parameter empty along with the MsgName and MsgPath parameters.
The pathname to the message file, i.e. “%SystemRoot%\System32\TKRN864.SYS”. If there is no message file then leave this parameter empty along with the MsgName MsgFamily parameters.Startup The driver startup mode: “Boot”, “System”, “Automatic”, “Manual”, or “Disabled”.
This function returns zero if the driver was installed or one if an error occurs.
Please refer to Microsoft documentation for further information on any of these parameters.
The GetWebPage function is used to retrieve the contents of a Web page.
A Web page address to be retrieved, such as http://www.secureagent.com or http://www.secureagent.com/about.htm
The resulting output list in the form of a standard stem array. The zero element (StemOutputList.0) will contain the number of lines of response; the first element (StemOutputList.1) will contain the first response line, etc.
This function returns the same number as in StemOutputList.0, which is the number of lines in the response. This number will be zero if no response was received or an error occurs.
StemOutputList.1 contains the time, in milliseconds, that it required to retrieve the page.StemOutputList.2 contains the size of the page.StemOutputList.3 contains the first line of the page data. The remaining StemOutputList lines contain the subsequent lines of the page data, if any.
The GetIPList function is used to retrieve a list of the network IP addresses of the computer on which the REXX program is executing.
[Hostname,] // name of computer (optional)StemOutputList // the resulting list
hostnameName of the computer on which the REXX program is executing.
The resulting output list in the form of a standard stem array. The zero element (StemOutputList.0) will contain the number of IP addresses, the first element (StemOutputList.1) will contain the first IP address, etc.
This function returns the same number as in StemOutputList.0, which is the number of IP addresses. This number will be zero if no IP addresses are found or an error occurs.
Will return a string of length characters with string centered within it. If length (0 or more) is greater than the actual size of string, the pad character will be added to both sides of string. If the string is wider than length, characters are truncated one right, one left, one right, etc. Center('TITLE',9) == " TITLE "Center('TITLE',9,'*') == "**TITLE**"Centre('TITLE',2) == "IT" /* European spelling */
This function is only designed for use with MCS (MVS operator) consoles. Usage on other types of 3270 session is undefined and can lead to unpredictable results and errors. String is read back from the operator’s input area to ensure keystrokes match before <ENTER> key actually is pressed.
CoaxIdString "COAX1", "COAX2", "COAX3" or "COAX4", defining to which device the text is to be sent.
Text Characters to be entered on the relevant device, starting at the current cursor position.
The <ENTER> key will be automatically pressed at the end of the command.
As with the CoaxText and CoaxPress functions, data will be entered into the type-ahead buffer to be processed in the normal way. Unlike these two functions, CoaxCommand will not return to the calling REXX program until after the text has actually been entered on the screen and the <ENTER> key has been pressed.
The return code for this function will contain valid information as follows:
OK -- data was entered without errors.Error -- the device was not installed or allocated.
Error -- the device is hung.Error -- the text contained an unsupported character.Error -- the device did not exist (i.e. if you specified "COAX37" by mistake).Error -- the device was busy and unable to accept entries.Error -- the device was not ready and was unable to accept entries.Error -- the device driver timed out when attempting an entry.Error -- the device was connected via TCP/IP and there was a TCP/IP-related error.Error -- too many commands were queued (there is a limit of 255 pending CoaxCommands across all COAX devices.
This function can replace a CoaxText followed by a CoaxPress (for the <ENTER> key) with no ill effects. Be aware that it DOES NOT attempt to clear any command line before starting to type its command. If you enter text in front of CoaxCommand, using CoaxText, it will append text to that command. This allows for the definition of prefixes, etc. as required.
pa1 page_down isteppa2 page_up last commandpf1-24 pf1-24 leftpor (power on reset) por (power-on reset) por (power-on reset)print reset newlineprinter_identity right pa1reset spmo pf1-12 (equate to 3178 pf13-24)
right start PFleftsystem_request stop PFrighttab tab printtest up printer_identityup refresh
If only string is specified, the reutrned result is ‘NUM’ (2), If string is a syntactically valid REXX number that can be added to ‘0’ without error, or ‘CHAR’ (3) otherwise.
If type is specified, the returned result is 1. If string matches the type, or 0 otherwise. If string is null, 0 is returned (except when type is "x", which returns 1 for a null string).
The valid types (of which the one letter is needed) are:
A - (Alphanumeric) ; returns 1 if string only contains characters from ranges "a-z", "A-Z", and "0-9".B - (Binary) ; returns 1 if string only contains the characters "0" and/or "1".L - (Lower case) ; returns 1 if string only contains characters from the range "a-z".
M - (Mixed case) ; returns 1 of string only contains characters from the ranges "a-z" and "A- Z".N - (Number) ; reutrns 1 if DATETYPE(string) would return ‘NUM’(2).S - (Symbol) ; returns 1 if string only contains characters that are vaild in REXX symbols.U - (Upper case) ; returns 1 if string only contains characters from the range "A-Z".W - (Whole numbers) ; returns 1 if string is a REXX whole number.
X - (heXadecimal) ; returns 1 if string only contains characters from the range "a-f", "A-F", "0-9". Also returns 1 if string is a null string, which is a valid hexadecimal string. (see page 91-92 of The REXX Language, by M.F.Cowlishaw) Examples:
The current date (as far as the operating system knows) is returned as a string. The default format is "[d]d Mmm yyyy". By using the FIRST letter of an option, other formats are obtained:
Base – returns the number of complete days (that is, not including the current day) since and including the base date, 1 Jan 0001, in the format ‘dddddd’ (no leading zeros or blanks). This base date is determined by extending the current Gregorian calendar
backward (365 days each year, with an extra day every year tat is divisible by 4, except century years that are not divisible by 400).
Note: The expression DATE (‘B’)//7 returns a number corresponding to the day of the week, with 0 indicating Monday. DATE (‘B’) would have returned 693595 on 1 Jan 1900.
Century - day of this century. January 1, 1900 is day 1 - Format ‘ddddd’Days - day of current year. Format ‘ddd’European - Format ‘dd/mm/yy’Julian - year and days of current year. Format ‘yyddd’
Month - current month in mixed case. Format ‘Mmm[mmmmm]’Normal - as shown aboveOrdered - Format ‘yy/mm/dd’Standard - Format ‘yyyymmdd’USA - Format ‘mm/dd/yy’Weekday - day of week in mixed case. Format ‘Dddddd[ddd]’
JULIAN = date in Julian format YYYY.DDDDAYNAME = full name of the day in English, eg. MondayMONTHNAME = full name of the month is English, eg. AprilDD = two-digit day number within the monthYYYY = four-digit year, eg. 1997DOC = Day number Of this Century, the same as Date("C")DM = number of Days in the Month, eg. for May it would be 31
36x = number of Days In the Year, always 365 or 366 for leap years
D = single-digit Day Of the Week number with Monday being zeroDDMonYYYY = date in "Military" format, eg. 09May1959WKNo = week number 01 to 52 with weeks starting on Mondays
BASE = number of days since 01Jan 0001
For example, the 1st of November 1997 would return:"11/01/1997 1997.305 Saturday November 01 1997 35734 30 365 5 01Nov1997 44 729328"
Note: Week number 1 may start at the end of the previous year and that all returned values will have leading zeros as required.
The first optional parameter is a date, in various allowed formats, for which the output should be prepared. The formats allowed are as follows:
MM/DD/YYYY or MM/DD/YY (if in 1900-1999) or MM/DD (current year assumed)DDmmmYYYY or DDmmmYY (if in 1900-1999) or DDmmm (current year assumed)YYYY.DDD or YY.DDD (if in 1900-1999) or .DDD (current year assumed)DDDDD (this is the day in the current century as returned by Date("C")
Input values are case-insensitive and leading zeros can be omitted.
The second optional parameter is a number of days to offset the date given as the first parameter before the output is prepared. It may be negative to indicate earlier dates. Dates before 1900 or after 2099 are not supported.
Starting at character position n (1 or greater), length (positive value) characters are deleted from string. When no length is specified, all remaining characters are deleted. Where the character position is greater than the size of the string, the string is returned in full.
DialPager allows the user to specify a com port, the pager telephone number, and the caller’s return telephone number. Additional option is the setup of modem initialization. If this is not specified, Dialpager uses the default setting provided by the factory.
ComPort: The com port to which the modem is connected.
Pager Phone No: The pager’s telephone number. A "P" in front of this number specifies a pulse mode; otherwise, the default is tone mode.Calling Phone No: The return caller’s telephone number or PIN and then telephone number.
Option: Any modem setting that you wish to set differently from the factory default settings.
Syntax: ENQ(Serializer Name,Time Out) or DEQ(Serializer Name,Time Out)
If you wish to serialize the running of multiple REXX programs, you should integrate these REXX commands into your program.
To start the serializing process:
X=Enq(serializer name, time out)for example:X=Enq(task.1,-1)
The time out is a period, expressed in seconds, that the program should try to get the Enq function executed. If you specify "-1", the program will try forever. If you specify "0", the program will try only once. The program will return either:
X=0 (indicates success)or
X=non-zero (indicates failure)
If you want to insure that only one copy of a program runs at a time, then:
X=Enq(task.1,0)IF X <> 0 then exit
Good programming requires you to relinquish the Enq function (SuperVision will relinquish in the absence of a direct command). You will need to issue the Deq function as follows:
Where ‘str’ is a string containing the name of a file previously opened by RECORDIN(), RECORDOUT(), LINEIN, or LINEOUT. If no path is specified, the file will be closed in the c:\SV or Sv4 directory. To close a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., '.\filename.ext'). Returns "0" if the file could be closed properly, "1" otherwise.
Note: It is not normally necessary to use this function, as all files opened by a REXX program are automatically closed when it terminates.
Where ‘str’ is the name of the desired [path]file. If no path is specified, the file will be checked in the working directory as specified in the SETTINGS DIALOGUE OR IN THE PROFILE (.INI). To check a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., '.\filename.ext'). Returns: "1" if the file exists, "0" otherwise.
Note: This function uses the MS-DOS "findfirst" directory search function to locate the file. Thus, if a DOS wildcard is included in the filename, FILEEXISTS will still work -- but it will return "1" (TRUE) if ANY file exists matching the wildcard. Thus, FILEEXISTS('*.log') will return TRUE if ANY files with the extension 'log' exist in the working directory. Exercise caution when using wildcards -- they might not give the exact results you intended!
my_stuff = FileExists('.\today.log')say my_stuff/* displays "1" if the file exists */
The TSO RECEIVE command syntax includes the following options:append—Specifies that the received file is to be appended to the end of an existing PC file.Note: If the append option is not specified and the specified PC file already exists, the received file will replace the existing PC file.ascii—Specifies that the EBCDIC-stored mainframe file be converted to ASCII before transfer. This option is recommended if you want the file to be readable on the PC.
crlf—Specifies that trailing spaces in the mainframe file records are to be deleted and that carriage return/line feed character pairs are to be inserted at the end of each record. This option is recommended if you want the file to be readable on the PC.
The CMS RECEIVE command syntax includes the following options (left parenthesis in syntax is required):
append -- Specifies that the received file is to be appended to the end of an existing PC file.
Note: If append is not specified and the specified PC file already exists, the received file will replace the existing PC file.
ascii -- Specifies that the EBCDIC-stored mainframe file be converted to ASCII before transfer. The ASCII option is recommended if a text file is to be readable on the PC.
crlf -- Specifies that trailing spaces in the mainframe file records are to be deleted and that carriage return/line feed character pairs are to be inserted at the end of each record. Crlf mode is recommended if you want the file to be readable on the PC.
The CICS RECEIVE command syntax includes the following options (left parenthesis in syntax is required):append—Lets you append the downloaded file to the end of an existing PC file.Note: If append is not used, the receiving file will be replaced by the downloading CICS file.ascii—Data is translated from EBCDIC to ASCII with the RECEIVE option. The ascii option is recommended if the file is to be readable on the mainframe and PC.binary—The data in the file to be sent or received is binary data. That is, data that is not readable. It is sent "as is" without any translation.
blank—This option specifies that trailing blanks are not to be deleted.crlf—Specifies that trailing spaces in the mainframe file records are to be deleted and that carriage return/line feed character pairs are to be inserted at the end of each record. Crlf mode is recommended if the file is to be readable on the PC.DCDF=dcdfname—Specifies the Data Conversion Descriptor File (DCDF) if field-level data conversion is to be performed during file transfer. DCDF must be present in the Host Transfer File and must be owned by the user issuing the RECEIVE.
DELETE—Once you receive a file owned by you, it is deleted from the host transfer file after it has been copied to the PC file. Delete is the default for files owned by you. (Files received from other users with the FROM=option are never deleted).FROM=USID—Retrieves a file that was stored as a public file or that another user shared with you. USID is the CICS/DOS/VS ID of the person who owns the file.HTF—The file is stored in/received from the host transfer file. (HTF, rather than TS, is the default).
KEEP—Specify KEEP if you do not want the file to be deleted.NOCRLF—The PC file to be received does not consist of logical records. No deletion or insertion of crlf character pairs will be performed. With RECEIVE, the blocks are concatenated into a single string.NLS=nn—Select the language in which the file transfer messages sent to the PC session are to be displayed. nn is the suffix of the message module (INWPMSnn).REPLACE—Specify replace if you want to replace an existing file.
TS—The file is received from a CICS temporary storage queue.
Where filemask is the name of the desired [path]file. If no path is specified, the file will be checked in the c:\SV or Sv4 directory. To check a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., '.\*.ext'). Returns the number of files that match the pattern mask and a compound variable array containing their names. The elements of the array will have the stem name in the function call and will be numbered from zero to the quantity of files found.
/* this will return the count and names of all of the files in the c:\SV or Sv4 directory */
file_count = FileSearch('C:\LOG\*.*','MY_LOG')
/* if, in this example, the following five files existed in that directory:
The TSO SEND command syntax includes the following options:append—Lets you append the uploaded file to the end of an existing TSO file. The append option is ignored if the specified TSO dataset does not exist. Append is not allowed if the TSO dataset is a partitioned dataset.Note: If you do not use append and the TSO data set name already exists on the mainframe, the existing file will be replaced by the uploaded file. You may not use append for members of a partitioned dataset.
ascii—Specifies that files stored in ASCII on the PC be converted to EBCDIC during transfer to the mainframe. Usually, alphanumeric files are stored in ASCII on the PC and EBCDIC on the mainframe. The ASCII option is recommended if you want the file to be readable on the mainframe.crlf—Specifies that carriage return/line feed character pairs present in the PC file are to be deleted from the mainframe file. Text data in the PC files commonly have a crlf character pair at the end of each line to denote the end of each record. Removing these character pairs with the crlf option makes the files readable on the mainframe.
irecl(n)—Specifies the Logical Record Length of the mainframe file, where n is the number of characters in each record. Set-length PC records longer than n and variable-length records longer the n-4 will be split into multiple mainframe records. If you omit irecl, the default is 80 for new files. For existing files, irecl is ignored.
blksize(n)—Specifies the block size of the mainframe dataset, where n is the length in bytes of a data block. If you are appending or replacing a dataset, blksize is ignored.
recfm(f)—Specifies that the mainframe file will contain fixed-length records. Records are padded with space characters if they are shorter than that specified with irecl or the default length. This is the default for new files unless crlf is specified.recfm(u)—Specifies that the mainframe file will contain records of undefined length.Note: For existing files, the recfm option is ignored.recfm(v)—Specifies that the mainframe file will contain records of variable length. This is the default for new files when crlf is specified.
Note: If is recommended that you use the recfm(v) option without the crlf option when you must avoid padding of mainframe records or deletion of trailing spaces—for example, binary (program) files contain variable length records.space—Specifies the amount of space you want to be allocated for a new dataset. If you use space, use the following syntax:
space(quantity[,extent]) [avblock(value) or tracks or cylinders]
For example: space(20,10) tracksIf you do not specify one of the options following extent, avblock(value), tracks, or cylinders, the default is avblock(blksize). The space option is ignored for existing datasets. Consult with your System Administrator for more information and for the space option to use.
The CMS SEND command syntax includes the following options (options must begin with a left parenthesis):append—Lets you append the uploaded file to the end of an existing CMS file. The append option is ignored if the specified CMS file does not exist.Note: If append is not used when the CMS filename already exists on the mainframe, the existing file will be replaced by the uploaded file.ascii—Specifies that files stored in ASCII on the PC be converted to EBCDIC before transfer. The ascii option is recommended if the file is to be readable on the mainframe.
crlf—Specifies that carriage return/line feed character-pairs present in the PC file should be deleted before being stored on the mainframe. Usually, alphanumeric data on the PC contains a crlf character pair at the end of each line to denote the end of each record. Deleting these character pairs using the crlf option lets you read the mainframe version of the file more easily.
irecl(n)—Specifies the Logical Record Length of the mainframe file, where n is the number of characters in each record. Set-length PC records longer than n and variable-length records longer the n-4 will be split into multiple mainframe records. If you omit irecl, the default is 80 for new files. For existing files, irecl is ignored.
recfm f—Specifies that the mainframe file will contain fixed-length records. Records are padded with space characters if they are shorter than that specified with irecl or the default length. This is the default for new files unless crlf is specified.recfm v—Specifies that the file will contain variable length records. This is the default for new files when crlf is specified.
Note: Use of the recfm v option without the crlf option is recommended when padding of mainframe records or deletion of trailing spaces must not occur.
The CICS SEND command syntax includes the following options (left parenthesis in syntax is required):ascii—Data is translated from ASCII to EBCDIC with the Send option. The ascii option is recommended if the file is to be readable on the mainframe and PC.binary—The data in the file to be sent is binary. That is, data that is not readable. It is sent "as is" without any transalation.crlf—Specifies that carriage return/line feed character pairs present in the PC file should be deleted before being stored on the mainframe. Usually, alphanumeric data on the PC contains a crlf character pair at the end of each line to denote the end of each record. Deleting these character pairs using the crlf option lets you read the mainframe version of the file more easily.
DCDF=dcdfname—Specifies the Data Conversion Descriptor File (DCDF) if field-level data conversion is to be performed during file transfer. DCDF must be present in the Host Transfer File and must be owned by the user issuing the SEND.FOR=USIDN—This option allows you to share a file with up to eight users. It can only be accessed by users who are logged on to CICS with a user ID specified in the USIDN parameter.HTF—The file is stored in/received from the host transfer file. (HTF, rather than TS, is the default)
NOCRLF—The PC file to be sent does not consist of logical records. No deletion or insertion of crlf character pairs will be performed. Each block becomes one record in the host file with SEND.NOREPLACE—Indicates that if a file with the same name already exists, it is not to be replaced by the new file. (NOREPLACE, rather than REPLACE, is the default).
NSL=nn—Select the language in which the file transfer messages sent to the PC session are to be displayed. nn is the suffix of the message module (INWPMSnn).
PRIVATE—Indicates that this is a private file accessible only by the originator.PUBLIC—Indicates that this file is available to everyone on the system.REPLACE—Specify replace if you want to replace an existing file.TS—The file is stored in/received from a CICS temporary storage queue.
Where ‘str’ is a string containing the name of the file whose size is desired. If no path is specified, the file will be checked in the C:\SV4 directory. To open a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., ".\filename.ext").
Returns "-1" if the file cannot be found; otherwise, the size of the file.
Note: This function uses the MS-DOS "findfirst" directory search function to locate the file. Thus, if a DOS wildcard is included in the filename, FileSize will still work—but it will return the size of the first file which matches the wildcard, which may not be what is desired!
Will return the decimal equivalent of the hexadecimal value in str. Note that hex values of '80000000' or greater will be converted to negative numbers, due to the implementation of signed arithmetic on the Intel 80x86 processor family.
Displays an input box containing message-text in which the user must respond to before continuing work in other SuperVision windows. The varname must be supplied and represents the name of the REXX local variable that will contain the value the user enters; the varname defaults to the value of itself, but can contain a value before InputBox is called. Thus, if the user does not update the value before pressing OK, the varname will equal itself.
Also, if CANCEL is pressed, then the varname will always equal itself, even if the user supplied a value. The field-length controls the length of the input field, is optional and defaults to 255. The title is also optional and replaces the default value of the title bar of the window. The title may be specified without the field-length, however the appropriate number of comma's must be supplied. The default value for title is Host ID, program name, and the program's address space identifier. (ASID).
CANCEL 0OK 1
To display the input box to the user with the message-text of "Test Input Box", then determine the key that was pressed and the value provided:
x=InputBox('Test Input Box',MYVAR')If x=1 Then
Say 'OK pressed'Else
Say 'CANCEL pressed'Say 'Input Value from User is ==>'MYVAR
To add a title:x=InputBox('Test Input Box','MYVAR',,'This is my Title')
To specify a length of 12 for the input field:x=Inputbox ('Test Input Box','MYVAR',12)
To specify a length and a title:x=InputBox('Test Input Box','MYVAR',12,'This is my Title')
The destination string has the new string inserted into it after position n (0 or more) for length characters. Padding will occur when the new string is less than length. If n is more than the size of the destination, padding occurs to reach the position.
Will return the character position of the last occasion the string sub_str occurs in string main_str. Searching proceeds backwards from the start position (default end-of-string). A zero is returned if it is not found.
Where name is the name of the text file to write. If no path is specified, the file to be written to will be opened in the same directory in which the REXX program is located.
To write to a file in the current directory, give the path to that directory or use the '.' alias for the current directory (i.e., '.\filename.ext').
If the file exists, it is opened and the current write position is set to the end of the file. Any output is then appended to the current contents of the file.
If string is specified, that string will be written to the end of the file along with the carriage return/line feed that always terminates the output. If string is not specified, a carriage return/line feed will still be written.
Returns a "0" after a successful write and a "1" if the write fails.
/* Examples *//* The following three calls */
LineOut("C:\MyFile.txt","This is a line of text.")LineOut("C:\MyFile.txt")LineOut("C:\MyFile.txt","Another line of text")
/* produce the following contents of MyFile.txt */This is a line of text0Another line of text/* Note that the second call produces only a carriage return/line feed, which appears as a blank line */
The logswitch function designed for VM upload. If file does not exist this function creates a separate .old file for the host specified and if it does exist it adds to the file so that it may be used for VM upload function.
Host: indicate host 1 thru 8. (A = 1, B = 2 ....... H = 8)
Option: this is to be specified only at the beginning of the program to reset the logswitch pointer into the file.
Default is 0, to reset specify 1.
x = logswitch(1, 1) /* this reset the logswitch pointer into the .old file *//* and if the file does not exist it creates the file */
x = logswitch(1) /* if file exist this will add it hte file, if not it will create the file */
Displays a message box containing message-text in which the user must respond before continuing work in other SuperVision windows. Optionally, the title, buttons, and icon can be specified. If message-text is the only argument specified, then the message box will default to the following characteristics:
Title will contain the Host ID, program name, and the program's address space identifier (ASID)
Buttons will be OKCANCEL, and the icon will be STOP. The return results depend on the buttons definitions below. You may specify buttons without title or icon without title and/or buttons, however the appropriate number of comma's must be supplied.
For example, to specify the icon without the title and buttons:
Returns a string containing recsize bytes (or a null string if end-of-file or DOS error). Where name is the name of the file to read. If no path is specified, the file will be opened in the c:\SV or Sv4 directory.
To open a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., '.\filename.ext'). The optional rec# is the number of the record to read from the file. If no rec# is given, a record is read from the location immediately
after the end of the previous read (or the beginning of the file if the file was not previously open).
Finally, recsize is the size of each record in bytes. Note that the first record in the file is numbered zero (0), not one (1)!
myline = RecordIn('.\MY.TXT',9,80)/* fetches TENTH line */
Where name is the name of the file to which data will be written. If no path is specified, the file will be opened in the c:\SV or Sv4 directory.
To write to a file in the current directory, give a path to that directory or use the '.' alias for the current directory (i.e., '.\filename.ext').
If the file exists, it is opened and the current write position is set at the end of the file so that any output is appended to the current contents of the file.
String is the text string to write at the specified location in the file. If no record size (recsize) is given, the length of the string is used as the record size (unless a random-access record number is specified). If a record size is given, the string is truncated or padded on the right to the specified length.
Rec# is the record number within the file where the write should occur. If this is omitted, the record is written immediately following the position of the previous write (or at the end of the file if it was not previously written).
Note that all records must be of the same size, since the rec# and recsize are used to calculate the file position for random access.
Warning: If rec# is given, then recsize MUST ALSO BE GIVEN in order to calculate the position of the start of the record. The string being written is truncated or padded on the right with the pad character as necessary to match this size. Returns a "0" if the write succeeded, "1" otherwise.
mystr = 'A location within a random access file'
RecordOut('.\mytext',mystr, 99, 80,'*')
/* outputs 80 byte text string padded with asterisks to the hundredth location within the file */
HostId String "A", "B", "C", etc. as appropriate, defining to which scrolling (host) window the
new name is to be applied.
Use "*" to indicate the current host session.
Text The new name for the given Host. The name is limited to a maximum of 30 characters.
The name cannot start with "COAX" or "TWINAX"; these are reserved names."default" will restore the original LU name used to make the connection.
Note: To reset the current session, use SetHostName("*","Default")
The return code for this function will contain valid information as follows:
OK -- data was entered without errors.Error -- invalid ‘HostId’ – the host ("A" through "P") must be active.Error -- reserved name – you cannot use a name starting with "COAX" or "TWINAX".Error -- ‘Text’ is too long for the new name – there is a limit of 30 characters.
This REXX function allows you to switch keygroups on or off under REXX control. Where KEYGROUP is the keygroup number from 1 to 16, and OPTION is either a one or zero, depending upon whether you want to activate or de-activate the keygroup respectively.
0 OK The operation was successfull.1 WARNING Keygroup was already activated.2 WARNING Keygroup was already de-activated.3 ERROR Keygroup does not exist. The corresponding file KeyGrpNN.ini does not exist.
Use AutoEdit to create one. (See AutoEdit for creating a new keygroup.)
Takes out any cases of a single char (default space) that are trailing and/or leading the string. There are only three possible single character options: Both, Leading, or Trailing. The default is Both.
A substring of length (default rest of string) characters is returned from the source string beginning at position n. The pad character will be used to achieve length as required including filling the entire substring if n is beyond the end of the source string.
Returns a substring from source string (of space delimited words) starting at word number n and containing the rest of the source string unless a length number of words is specified. Both trailing and leading blanks are omitted. Should n be greater than the number of words in the source, a null string is returned.
Allows activation of selected options from the SuperVision menu.
Menu—reference to the drop-down menu containing the itemItem—reference to the item to be selected
In both cases, the reference consists of the underlined letter from the appropriate menu entry.
/* example of the SVMENU function */
To select the "Host" menu and "Select/Goto Host C" item
x = SVMenu ("H", "C")
In each case, only the first character of the parameter is significant. Therefore, the "H" could have been given as "Host" for the menu parameter, perhaps for clarity. However, putting "Select/Goto Host C" for the item parameter would result in selecting the "SuperVision messages" entry, since it starts with the letter "S". For this reason, "C" was used to give the item parameter.
Note: Not all menu items are supported by this function. As a general rule, only those items that can be selected via a single hot key are supported (often denoted by a single underlined character).
Will return the current system time in "hh:mm:ss" format. Default is 24-hour style.
The option string is activated by the supplying first letter of its name. The options are:
Civil format "hh:mm:ssxx". Noon is 12:00:00pm. Midnight is 0:00:00am.
Elapsed format "sssssssss.uuuuuu" (seconds and microseconds). The internal stopwatch
value since the last reset is returned.
Hours format "hh". Hours since midnight. No leading zeros.Long format "hh:mm:ss:uuuuu". 24-hour system time including microseconds.Minutes format "mmmm". Minutes elapsed since midnight. No leading zeros.Normal format "hh:mm:ss". Same as default 24-hour clock.
Reset format "sssssssss.uuuuu". Seconds and microseconds since last internal stopwatch
reset and resets the stopwatch to zero.
Seconds format "sssss". Seconds elapsed since midnight. No leading zeros.
Time() == "7:30:00"/* 7:30 in the morning */Time('c') == "7:30:00am"Time('H') == "7"Time('M') == "450"Time('n') == "17:00:00"/* 5:00 in the afternoon */
The translate function acts by searching the input translate table, tablei, for each character in string. If the character is found (the first (leftmost) occurrence being used if there are duplication) then the corresponding character in the output translate table, tableo, is used in the result string; Otherwise the original character found in string is used. (see page 111 of The REXX Language, by M.F.Cowlishaw)
The TwinaxPress function allows you to press a specific key on the specified twinax. TWINAXn must be TWINAX1, TWINAX2, TWINAX3, TWINAX4, TWINAX5, TWINAX6, TWINAX7, and TWINAX8. Valid keys are shown below:
Return Codes: 0=OK 1=twinax not available 2=hung (undesired response)
VALID 5250 KEYSAttention Backspace Backtab ClearCommand Delete Down Duplicate
Verifies that the string is composed only of characters from reference, by returning the position of the first character in the string that in not also in reference. If all the characters were found in reference, "0" is returned.
If string is null, the function returns "0", regardless of the value of the third argument.
If reference is null, then the returned value is the value used for start, unless ‘Match’ is specified (in which case "0" is returned).
The default for start is "1", i.e., the search starts at the first character of the string. This can be overridden by giving a different start point, which must be positive.
The option may be either ‘Nomatch’ (default) or ‘Match’. Only the first character if the option is significant and it may be upper case or lower case, as usual. If ‘Match’ is specified, the position of the first character in string that is in reference is returned, or 0 if none of the characters were found (see page 113 of The REXX Language, by M.F.Cowlishaw).
Searches for a space delimited phrase in string and returns the position of the first word match. Returns a "0" if it cannot find it. It will search from the first word in string unless a start word position is supplied.
WordPos('and over','over and over and over again',3)== 4
The PARSE and ARG instructions have the ability to allocate parts of a specified input string to memory variables according to a template. The different kinds of controls within a template give these commands the option to split up the input string by numeric position, matched strings (patterns), and/or merely by space delimited words.
Elementary Parsing Comma as a Literal String
Parsing by an Exact Character Position Using PARSE ARG in the Destination Routine
PARSE VALUE 'The parking fee is being cut!' with abc
The template consists of the variables "a", "b", and "c". The space delimited words are read and assigned to the space delimited variables. "a" holds the value of "The", "b" holds "parking", and "c" holds "fee is being cut!".
If there are more variables than words to parse, the excess variables are assigned a null value. Note that the delimiting leading and trailing spaces for the first two variables have been removed.
The use of patterns can refine the assignment of variables when those patterns are anticipated as part of the input. Remember that the input string can also be a variable.
/* use literal comma */PARSE VALUE 'Avail. Dec. 1, 1993 to owners' with a ',' b c
In this PARSE statement, "a" will be assigned "Avail. Dec. 1" (everything up to but NOT including the comma) and "b" is assigned the year string INCLUDING the leading space
(" because there is a pattern being used at that point rather than just spaces and "c" gets "to owners" without the leading space. If there were no comma in the input string, the entire string would be assigned to "a" and the other variables would be set to null.
Parsing can be done by an exact character (or column) position which will designate the position along the input string that will begin assigning value to the next variable:
PARSE VALUE 'Avail. Dec. 1, 1993 to owners' with a 8 b 16 c
In this example, "a" will receive everything from positions 1-7 ("Avail. "). "b" will get everything from positions 8-15 ("Dec. 1, ") and "c" gets the rest ("1993 to owners").
These template control types may be mixed as required:
PARSE VALUE 'Avail. Dec. 1, 1993 to owners' with 8 a ',' b 20 c dWill result in "a" having "Dec. 1", "b" having " 1993", "c" having "o", and "d" having "owners".
Should we want to assign everything to the comma and skip the rest of the input string, we can use this:
PARSE VALUE 'Avail. Dec. 1, 1993 to owners' with a ','
Then "a" will have "Avail. Dec. 1".
If we just want to skip the first or last words of the input string and not use up variable names, the period "." acts as a dummy (or placeholder):
PARSE VALUE 'Thirty two gigabytes of online storage' WITH . . x .
will assign "gigabytes" to variable "x" and discard the rest. This can be used with other controls.
There is a general rule that parsing will go from left to right and as REXX encounters symbols in the template, parts of the input string will be assigned to variables or skipped. Assignments or skips can be by space delimited words, up to a specified character pattern, or to a specified character position. All template controls can be mixed together as required.
/* parse a variable containing a text string and make it upper case */
this_string = '*Heat sink with built-in cooling fan on every chip'PARSE UPPER VAR in_string star 2 x1 '-' . b2 .SAY x1/* displays "HEAT SINK WITH BUILT" */SAY b2/* displays "COOLING" */
In the above example, the text in this_string is converted to upper case (option used for this example). The first character is "*" and it alone is assigned to "star" because the "2" in the template begins assignment into "x1" at the second character position. Assignment to "x1" continues until the "-" is encountered in the template. Then "IN" is discarded because of the placeholding period character. The word "COOLING" is assigned to "b2" and the remainder of the string ("ON EVERY CHIP") is discarded because of the final placeholding period.
REXX supports file I/O, output to SuperVision and input from the operator on the SuperVision Console.
Because REXX can read text files, a program can be written to read in a console log from SuperVision and play it back to SuperVision as Host Output. The capability of writing text files can be used to write logs during testing of SuperVision automation routines.
However, it is extremely poor programming practice to actually do so because of several reasons.
1. It makes the program confusing to read and support. Quite frequently, programs have to be changed after months or years of use. The original programmer can hardly be expected to recall all the circumstances and reasoning surrounding the creation of some code. Should another programmer need to make changes, coding clarity becomes critical. The new programmer is expecting a keyword to have just one meaning and not two or three as in the examples above.
2. It complicates editing. Most text editors have a "Search and Replace" feature. If a keyword is used as a variable name and the editor is told to replace all occasions of "say" (as in example number 3) with "pay" then all occasions of the "SAY" instruction would also be replaced. One can easily imagine the number of errors reported if the program is then executed.
3. It decreases program portability. Should someone want to run a REXX program with mixed keywords/labels/names on a system that has implemented strict controls on keyword usage, an extensive rewrite would be necessary for the program to run.
The REXX Editor program (rexxedit.exe) is automatically loaded into the SV directory (Sv4 if running a version prior to 5.0) as part of the Typical setup type when SuperVision is installed. If, however, the REXX Editor should need to be re-installed as a stand-alone program, or if you chose a setup option other than Typical, complete the following instructions for installing SuperVision. You will be prompted at the point of custom setup** to select only the REXX component.
NOTE: REXX Editor upgrades will automatically install over and replace any previous versions.
Create a New REXX File Open an Existing File Save the File Cut Highlighted Text Copy Highlighted Text Paste Highlighted Text Print a Window Options