Basic REXX

Basic Concepts

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

© SecureAgent Software, Tulsa OK USA. All rights reserved.Dealing with Reality

REXX is a tool for use in the real world. It is designed for general use by you and your associates. Features that yield unpredictable results when misused have not been put in this language.

A reasonable level of consistency has been designed into the syntax of this language so that usability is increased and the susceptibility of human error decreased.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Dynamic Scoping

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.

© SecureAgent Software, Tulsa OK USA. All rights reservEmphasis on Symbolic Manipulation

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

displays this:

25% OF CAPACITY

A blank causes continuation for the SAY, not the termination of it.

See also: Basic Concepts

© SecureAgent Software, Tulsa OK USA. All rights reserved.ed.Keeping the Language Small

The fewer keywords to be memorized the better, making REXX one of the easiest languages to learn. Documentation is shorter and clearer with a smaller language.

An experienced user can eventually learn the entire language.

Finally, a small language is much easier to implement than a large one.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Natural Data Typing

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.No Defined Size or Shape Limits

REXX does not force maximum limits on the size or shape of tokens or data (though operating system implementation limits may exist).

© SecureAgent Software, Tulsa OK USA. All rights reserved.Nothing to Declare

Only LABELS need be explicitly declared. All local variables can be declared upon use.

If you want to declare, initialize, and document your variables at the beginning of your program, you are perfectly free to do so if you think it helps you write a better program.

If you intend to use global variables, then you should declare and document them.

GLOBAL HOST a_variable/* initial declaration of a global variable */

sub_total = worknum1 + worknum2

/* dynamically create a local variable */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Readability

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.

For example:

/* 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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Syntactic Units

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.System Independence

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Tokens

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

Operators Special Characters Symbols

© SecureAgent Software, Tulsa OK USA. All rights reserved.Comments

Start with " /* " and end with " */ ". They can be put anywhere in a program, be nested, and of any length. Comments will act as separators between other tokens.

/* All good REXX programs should begin with a comment /* nested */ */

© SecureAgent Software, Tulsa OK USA. All rights reserved.

Implied Semicolons and Continuation Characters

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

See also: Tokens

© SecureAgent Software, Tulsa OK USA. All rights reserved.Literal Strings

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Numbers

Numbers are one or more characters representing decimal (0-9) values which may be optionally preceded by a plus or minus sign.

/* examples of numbers */

123-456'789'+002468

© SecureAgent Software, Tulsa OK USA. All rights reserved.Operator Tokens

The characters * / + - % | & \ < > = are used alone or in combination as arithmetic, logical (Boolean) and comparative operators.

* Multiply/ Divide+ Add- Subtract% Integer Divide// Remainder| Boolean OR (if either True, returns 1) & Boolean AND (if both True, returns 1)&& Boolean XOR - eXclusive OR (if one, not both, True, returns 1)\ Boolean NOT (if the opposite, returns True)

< Less than<=, \> Less than or equal to, not greater than> Greater than>=, \< Greater than or equal to, not less than= Equal numeric or string (after padding shorter string with zeros or spaces)

<>, \= Not equal== Strictly equal (if exactly alike, returns 1)\== Strictly not equal<< Strictly less than (all characters count)>> Strictly greater than (all characters count)

<<=, \>> Strictly less than or equal, not strictly greater>>=, \<< Strictly greater than, not strictly less than

© SecureAgent Software, Tulsa OK USA. All rights reserved.Special Characters

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Symbols

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.

/* examples of symbols */

REXX_text.book!

$sales

SAY

© SecureAgent Software, Tulsa OK USA. All rights reserved. Expressions and Operators

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 */


Concatenation

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" */

SAY 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" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Arithmetic

Valid numbers are combined with standard operators (such as * / + -).

SAY 7 * 7 + 1 /* displays "50" */SAY 50 / 2 - 1 /* displays "24" */SAY -3 * 50 + 5 /* displays "-145" */x=3;SAY x * (x * 3) /* displays "27")

Assignment Summary Example:

x = 15 - (1 + 2) * 3/* same as "x = 15 - 9" */x = x * 2 /* result is 12 */ alpha = an 'example'

/* result is "AN example" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Comparative

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 */


Logical

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" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parentheses and Precedence of Operators

When an expression is seen by REXX, the normal mode of evaluation is from left to right subject to the presence of parentheses and operator precedence.

Terms within parentheses are evaluated and acted upon first.

They are followed in evaluation order by prefix operators (+ - \), arithmetic operators (* / % // + -), concatenation operators ([space] || [abuttal]), comparison operator (= == > < >= \> << \>> etc.), and, finally, the Boolean operators (& | && \).

Operator Precedence Summary Example:

x = 1 + 3 * 3/* same as "x = 1 + 9" */x = (1 + 3) * 3/* same as "x = 4 * 3" */x = 1 + -3 + 5/* same as "x = -2 + 5" (or "5 - 2") */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Clauses

CLAUSES may include expressions that produce results, and will fall into one of five different categories:

Assignments Commands Instructions Labels Null Clauses

© SecureAgent Software, Tulsa OK USA. All rights reserved.Assignments

With an assignment clause, the value of a symbol can be set. It has the form of:

symbol = expression [;]

an_unnecessarily_long_symbol_name_indeed! = '?'mytotal = 2 + 4 + (1000 / 50)

© SecureAgent Software, Tulsa OK USA. All rights reserved.Commands

Commands are single clauses consisting of a single expression. The result of the expression is not assigned to a symbol, as in an assignment, but is passed as a command string to SuperVision.

/*send command to SV*/'set demo on'

© SecureAgent Software, Tulsa OK USA. All rights reserved.Instructions

The first word of an instruction is a keyword that identifies the nature of the instruction. A good example of an instruction is the DO instruction.

/* example of DO */

DO/* keyword causing execution of lines below */ SAY 'hello'/* another keyword instruction */ END /* sub-keyword instruction terminates "DO" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Labels

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 */

Null Clauses

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Assignments and Variables

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)

© SecureAgent Software, Tulsa OK USA. All rights reserved.Constant Symbols

Begin with a numeric character (0-9). They are numeric symbols and will always have the same value. That is, a "1" will always be a one and will constantly be that value and no other.

/* numeric constants */

1234567000987246810

© SecureAgent Software, Tulsa OK USA. All rights reserved.Simple 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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Compound Symbols

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Stems (as part of Compound Symbols)

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Commands to External Environments

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.

Note: These commands are not case sensitive.

.BEEP FILE file1 file2 .COPY FILE file1 file2 .DATE([option]) .DELETE FILE or file .DIALPAGER ('ComPort','Pager Phone No.','Calling Phone' [,'Options']) .DOS dos_function or .DOSCOMMAND(‘Doscmd’, ‘Outfile’) .HELP

.LIST .MSG <host nodename> text_message or Msg(‘Node’, ‘Host’, ‘Msg’) .PLAY soundwave.wav or .PlaySound(Wav file) .RENAME file 1 file 2 .REXX file or .REXX file argument .SEND <host nodename> command or Send(‘Node’, ‘Host’, ‘Msg’)

.SETCOMPORT('ComPort' [, 'Baud Rate'] [, 'DataBit'] [, 'StopBit'] [, 'Parity'])

.SCRIPTfilename .SHUTDOWN seconds .START rexx_prog .STOP rexx_prog or TERMINATE(‘Host’, ‘Rexxname’, [,ASID]) .STOPALL .TERMINATE(‘Host’, ‘Rexxname’, [,ASID]) or .STOP rexx_prog

.TIME

© SecureAgent Software, Tulsa OK USA. All rights reserved..Copy

Causes the designated file name to be copied.

Syntax .COPY FILE file1 file2

Parameters Part Description

FILE The word FILE must follow the word COPYfile1 Name of file the user wishes to copy

file2 File name the user wants to copy into

Note: This command is not case sensitive.

© SecureAgent Software, Tulsa OK USA. All rights reserved..Delete

Causes the specified file name to be deleted.

Syntax .DELETE file filename.doc


file The word FILE must follow the word DELETEfilename This is name of the file that the user wishes to delete


© SecureAgent Software, Tulsa OK USA. All rights reserved..DOS

Issues a specified DOS command directly from the command line of a SuperVision scrolling window.

Syntax .DOS dir *.doc or .DosCommand('Doscmd','Outfile')


dos_function This may be any valid DOS command that DOS provides.

Remarks

We suggest all NEW programs use the following overhead-reducing advanced method and where possible, convert the standard method to the advanced:

X=DosCommand('Doscmd','Outfile')



.DosCommand

Issues a specified DOS command directly from the command line of a SuperVision scrolling window.

Syntax .DOS dir *.doc or .DosCommand('Doscmd','Outfile')


dos_function This may be any valid DOS command that DOS provides.

Remarks


X=DosCommand('Doscmd','Outfile')



.Msg

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')


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!!!

Remarks


X=Msg('Node','Host,'Msg')

Notes:

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.


.Play

Feature that may be utilized if the system has a soundcard. Sends a command specifying a particular WAV file that should be launched.

Syntax .PLAY soundwave.wav or PlaySound(Wav file)


soundwave File name of .WAV file to be playedWav file File name of .WAV file to be played

Example .play welcome.wav

Remarks


X=PlaySound(Wav file)



.PlaySound

Feature that may be utilized if the system has a soundcard. Sends a command specifying a particular WAV file that should be played.

Syntax .PLAY soundwave.wav or PlaySound(Wav file)


soundwave File name of .WAV file to be playedWav file File name of .WAV file to be played

Example .play welcome.wav

Remarks


X=PlaySound(Wav file)


© SecureAgent Software, Tulsa OK USA. All rights reserved..Rename

Allows a file to be renamed from the command line of a SuperVision scrolling window. File1 will be renamed according to the parameter set in file2 when this command is issued.

Syntax .RENAME file1 file 2


file1 Name of file user wishes to renamefile2 Name of new file

Example .rename oldfile.doc newfile.doc


© SecureAgent Software, Tulsa OK USA. All rights reserved..REXX

This command can be issued at any scrolling (host) window command line. The argument string following the command will be interpreted as REXX code and executed by SuperVision.

Syntax .REXX file or .REXX file argument


file Name of REXX program to be executedargument String to be applied along with REXX program

Example .rexx Say "Hello"

Will display a greeting in the active scrolling(host) window.


© SecureAgent Software, Tulsa OK USA. All rights reserved..Send

Causes a particular command to be sent to, and issued on, a specified node (host).

Syntax .SEND <host nodename> command or Send(['Node'], 'Host', 'Msg')


host The host window where the message is to be sent.nodename The name of node where the message is to be sent.Command The command the user wishes to send. This command may start

a REXX program.

Example .send <A sv4_node01> setdate


X=Send('Node','Host','Msg')

© SecureAgent Software, Tulsa OK USA. All rights reserved..Shutdown

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


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.

© SecureAgent Software, Tulsa OK USA. All rights reserved..Start

This command will cause a particular REXX program to be launched.

Syntax .START rexx_prog


rexx_prog The name of a REXX program the user wishes to start.

Example .start settime


© SecureAgent Software, Tulsa OK USA. All rights reserved..Stop

This command will cause a particular REXX program to be stopped.

Syntax .STOP rexx_prog or Terminate('Host', 'Rexxname', (ASID))


rexx_prog The name of a REXX program the user wishes to stop.

Example .stop forever-loop


X=Terminate('Host','Rexxname',(ASID))


© SecureAgent Software, Tulsa OK USA. All rights reserved.Terminate

This command will cause a particular REXX program to be stopped.

Syntax .STOP rexx_prog or Terminate('Host', 'Rexxname' (,ASID))


rexx_prog The name of a REXX program the user wishes to stop.

Example .stop forever-loop


X=Terminate('Host','Rexxname'(,ASID))


© SecureAgent Software, Tulsa OK USA. All rights reserved.Keywords/Instructions

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

RETURN [expression]; REXXDUMP SAY [expression]; SEARCH SELECT ;WHEN;OTHERWISE TRACE options WAIT [expression];

© SecureAgent Software, Tulsa OK USA. All rights reserved.CALL name [expression]

Syntax: CALL name [expression];

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.

/* sendarg.usm */CALL my_macro 'quick brown fox'/* send string literal argument */

my_animal = 'fast yellow canary'

/* create a local variable */CALL my_macro my_animal/* use variable as argument */

CALL my_macro 'slow '||'gray '||'snail'/* send result of abuttal */EXIT/* end of program */

/* my_macro.usm */PARSE ARG speed color animal /* parse into 3 local variables */SAY speed color animal/* display them */

/* the first time, my_macro.usm will display "quick brown fox" *//* the second time, it will display "fast yellow canary" */

/* the third time, it will display "slow gray snail" */

See also: Keywords/Instructions

© SecureAgent Software, Tulsa OK USA. All rights reserved.The DO Instruction

Syntax: The DO Instruction

Simple DO Group Simple Repetitive Loops Counting Loops Conditional Loops

The general form of the DO instruction is:

DO [repetitor] | [condition]; [instruction_group] END [symbol];

The repetitor can be: FOREVER (this literally means what it says) numexp (an expression that evaluates to a number)

The conditions are: UNTIL logical_expression (resulting in 1 or 0) WHILE logical_expression (resulting in 1 or 0)

The instruction_group is one or more instructions to be executed within the loop.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Simple DO Group

The simplest form of DO is for the purpose of grouping instructions.

IF month='March' THEN DO /* If the condition is true */ season='Spring' game = 'Baseball' SAY 'Play ball!' END /* all instructions up to here will be executed */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Simple Repetitive Loops

The inclusion of the repetitor FOREVER will produce an infinite loop.

DO FOREVER SAY 'infinite loop' END /* will keep looping forever */

A simple numeric value or expression for a set number of executions.

DO 3 /* do something 3 times */ SAY 'a group of 3 lines' END /* print a line 3 times *//* build an expression */

a=10/* assign values to variables */b=25DO (b-a)

/* same as "DO (25-10)" or "DO 15" */ SAY 'See 15 lines of text'/* show this line 15 times */ END/* end of construct */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Counting Loops

DO n = 1 TO 3 /* will loop three times with the variable ‘n’ taking the values of 1, 2 and 3 */

SAY "This is line" nEND

DO n = 1 TO 10 BY 2 /* will loop five times with the variable ‘n’ taking the values of 1, 3, 5, 7 and 9 */


DO n = 6 TO 1 BY –1 /* will loop six times with the variable ‘n’ taking the values

of 6, 5, 4, 3, 2 and 1 */


© SecureAgent Software, Tulsa OK USA. All rights reserved.Conditional Loops

The loop will continue as long as the condition is true.

i = 1/* initialize our loop variable */

DO WHILE i <= 10/* evaluation prior to execution */ SAY i/* displays value of "i" */ i = i + 1/* increment our loop variable */ END /* loops from 1 to 10 */

i = 1/* initialize loop variable */

DO UNTIL i = 10 /* same as "DO WHILE i < 10" */ SAY i /* displays loop variable from 1 to 9 */

i = i + 1/* increment variable */ END /* loops from 1 to 10 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.DROP GLOBALS

Syntax: DROP GLOBALS [ HOST | NODE ];

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.)


DROP varnames

Syntax: DROP varnames;

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 */


EXIT [expression]

Syntax: EXIT [expression];

Unconditionally terminates a program (regardless of nesting level or internal routines in progress) with the numeric result of the expression being returned in the RC variable.


© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT <keyword>

Syntax: EXTRACT keyword [optional parameter];

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 .

The following EXTRACT keywords are supported:

COAXn CONNECT HOSTID HOSTNAME HOSTTASKS KEYGROUPS hostid NETCONNECTS nodename NETHOSTS nodename NETNAMES NODEID

NODENAME NODETASKS NODETYPE OIAn TASK

Note: Nodename may be specified either as a full nodename, or as the text portion only. If only the text portion is specified, then the first match encountered in the node list is returned.

Because NETHOSTS and NETCONNECTS are the only EXTRACT subkeywords which require a parameter, it is recommended that they be the last subkeyword given in an EXTRACT command


© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT COAXn

Note: n can be 1, 2, 3, 4, 5, 6, 7, 8, or 9, so the actual keyword is COAX1, etc.

COAXn.0 = m (number of dumped lines), or 0 if inactiveCOAXn.1 = <text of first line on COAX emulation screen>COAXn.m = <text of last line on COAX emulation screen>

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT Connect

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT HostID

HOSTID.0 = 1HOSTID.1 = host ID character (A-P or S) of scrolling (host) window the REXX program is running in.

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT HostName

HOSTNAME.0 = 1

HOSTNAME.1 = <name of current host>HOSTNAME.2 = Fully qualified name of window

Example:Extract HostName

HOSTNAME.0 = 2HOSTNAME.1 = GISMVSHOSTNAME.2 = GISMVS@SNS_TESTSYSTEM

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT HostTasks

Returns information about all the currently running REXX programs (tasks) started under this scrolling (host) window.

HOSTTASKS.0 = n (the number of tasks in the list)HOSTTASKS.1 = the name of the first taskHOSTTASKS.n = the name of the last task in the list

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT KeyGroups hostid

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NetConnects nodename

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.

See also: EXTRACT keyword

Keywords/Instructions

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NetHosts nodename


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>

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NetNames


NETNAMES.0 = n (number of workstations on the network i.e. # of entries in network node list)NETNAMES.1 = <full name of first workstation node in list>NETNAMES.n = <full name of last node in list>

'Full' names consist of 10 text characters (padded on the right by blanks if necessary) followed by the 12 hex digits of the 'unique ID' of the network hardware.

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NodeID

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).

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NodeName

NODENAME.0 = 1NODENAME.1 = the 10-char. text portion of the workstation name which is set by the user.

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NodeTasks

Returns information about all the currently running REXX programs (tasks) started on this node.

NODETASKS.0 = n (the number of tasks in the list)NODETASKS.1 = the name of the first taskNODETASKS.n = the name of the last task in the list

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT NodeType

NODETYPE.0 = 1NODETYPE.1 = six-digit number indicating version of SuperVision currently running the REXX program. Major release – minor release – service pack (i.e. 050303)

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT OIAn

Note: n Œ {1, 2, 3, 4, 5, 6, 7, 8, 9}, so actual keyword is OIA1, etc.

OIAn.0 = 3, or 0 if COAXn is inactiveOIAn.1 = <text of OIA (COAX emulation status line)>OIAn.2 = cursor x-position (1..#cols) on emulated screenOIAN.3 = cursor y-position (1..#rows) on emulated screen

© SecureAgent Software, Tulsa OK USA. All rights reserved.EXTRACT Task

TASK.0 = 3TASK.1 = <name of current task> The name of the currently running REXX program.TASK.2 = <class of current task> "auto" if program started as auto-response to a message

"dynamic" if program was started manually

TASK.3 = <ASID> of the REXX program

© SecureAgent Software, Tulsa OK USA. All rights reserved.FLUSH

Syntax: FLUSH

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.GLOBAL

Syntax: GLOBAL [NODE | HOST] name [name...]

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" */


© SecureAgent Software, Tulsa OK USA. All rights reserved.IF Logical Expression

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.INTERPRET

Syntax: INTERPRET [expression];

Executes instructions which have been built "on the fly" (dynamically).

shoe = 'SIZE'INTERPRET shoe "= '8 1/2 EEE'" /* Same as SIZE = '8 1/2 EEE' */

SAY SIZE/* displays "8 1/2 EEE" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.ITERATE

Syntax: ITERATE;

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 */

/* displays "1 2 4 5" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.LEAVE

Syntax: LEAVE;

Terminates DO loop. Control passes to the first line after the END of the innermost loop it is called from.

DO 5/* outer loop goes 5 times */ j = 0/* set loop variable */ DO WHILE j <= 5

/* set inner loop condition */ j = j + 1/* increment it */ IF j = 3 THEN LEAVE/* terminate inner loop */ SAY j/* display loop variable */ END/* bottom of inner loop */

END/* bottom of outer loop *//* displays "1 2 1 2 1 2 1 2 1 2" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.NOP

Syntax: NOP;

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.PARSE

Syntax: PARSE [UPPER] ARG [template]

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

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse ARG

Parsing occurs upon the string passed to the function, subroutine, or program.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse History

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse MSG

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".

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse Source

The template will receive the REXX name of the program being parsed.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse Value

After evaluation, the resulting character string is parsed.

parse value date(u) with month '/' day '/' year

/* splits USA style date into 3 variables with the patterns "'/'" showing PARSE where the splits are */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse VAR name

The parsing occurs upon the value of the variable. In this example, the UPPER option is used.

string = 'Four score and seven years'PARSE UPPER VAR string word1 word2 rest_of_it ;

The first two variables in the template (word1 & word2) will contain "FOUR" and "SCORE" respectively. The third variable will hold the remainder of the string in UPPER CASE form.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parse Version

Shows the revision level of REXX in operation. The first word will always be "REXX", next is the revision level, and lastly is the date in the form "dd Mon yyyy".

PARSE VERSION lang rev date_str

The above will yield "REXX_" in lang, something like "1.30" in rev (a 4 character release level), and a date such as "01 Jul 1993" in the last variable.

© SecureAgent Software, Tulsa OK USA. All rights reserved.RETURN

Syntax: RETURN [expression];

Returns control to a calling or invocation point with an optional RESULT value.

© SecureAgent Software, Tulsa OK USA. All rights reserved.REXXDUMP

Syntax: REXXDUMP

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".

© SecureAgent Software, Tulsa OK USA. All rights reserved.SAY

Syntax: SAY [expression];

Causes output to SuperVision.

SAY "The square of 15 is" 15*15/* displays "The square of 15 is 225" on the SuperVision window*/

© SecureAgent Software, Tulsa OK USA. All rights reserved.SEARCH

Syntax: SEARCH[TIME max_secs] [COUNT max_msgs][;]

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

© SecureAgent Software, Tulsa OK USA. All rights reserved.SELECT

Syntax: SELECT;WHEN;OTHERWISE

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 */

SELECT

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'

END

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.TRACE options

Syntax: TRACE options

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.WAIT

Syntax: WAIT [expression];

The command will pause program execution for the specified time. The numeric expression may be a value from 1 to 255 (seconds) when it is called from a REXX program.

WAIT 8/* pause for 8 seconds */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Function Calls

A call to a built-in routine that returns a result string (function) may be part of an expression where such a term would be valid (as in a literal string) in this form:

function_name( [expression] [,[expression]] . . . )

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Built-In Functions (Syntax Rules)

Always supply a parentheses set next to the name of the function even if no arguments are needed (i.e. "FUNC( )" not "FUNC ( )" or "FUNC")

A null string may be an argument or a result.

When string lengths or character/word positions are supplied in an argument, the numbers must be positive integers.

A comma may be used to show the omission of an optional final argument. Example, CENTER ('THIS',8,) will show the absence of an optional padding character.

Any pad character is, as the name implies, a single valid character (one byte only).

String type sub-options within a function are not case sensitive.

Select function by first letter:

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: A

Abbrev (string_arg,string[,length])

Abs (number) Address() Alert ('ATTN WARN OR PRIO', 'MSG') Arg ([n[,option]])

Admin Functions AdminDriverAdd AdminDriverGetDetail AdminDriverGetList

AdminDriverRemove AdminDriverStart AdminDriverStartup AdminDriverStop AdminEventLogGetDetail AdminEventLogGetList AdminPerfMon Functions - Introduction AdminPerfMonGetCounters AdminPerfMonGetInstances AdminPerfMonGetObjects

AdminPerfMonGetValues AdminRegistryAddKey AdminRegistryGetKeyList AdminRegistryGetValueDetail AdminRegistryGetValueList AdminRegistryRemoveKey AdminRegistryRemoveValue AdminRegistrySetValue AdminRegistryAddKey

AdminServiceAdd AdminServiceGetDetail AdminServiceGetList AdminServicePause AdminServiceRemove AdminServiceResume AdminServiceStart AdminServiceStartup AdminServiceStop AdminTaskGetList

AdminTaskGetThreadList AdminTaskStart AdminTaskStop

© SecureAgent Software, Tulsa OK USA. All rights reserved.Abbrev Function

Syntax: Abbrev(string_arg,sting[,length])

Checks if string_arg matches string for optional length along string_arg. Returns 1 for true; 0 for false.

Abbrev('Oklahoma','Okla',4)== 1 /* exact */ Abbrev('Oklahoma','OK')== 0 /* case counts */ Abbrev('Oklahoma','Okla',5)== 0 /* too few characters in second

© SecureAgent Software, Tulsa OK USA. All rights reserved.Abs Function

Syntax: Abs(number)

The absolute value of number is returned.

x = Abs(-409)/* "X" is now 409 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Alert Function

Syntax: Alert(category, msg[,color])

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')

© SecureAgent Software, Tulsa OK USA. All rights reserved.Arg Function

Syntax: Arg([n[,option]])

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) */

© SecureAgent Software, Tulsa OK USA. All rights reserved..Beep

Syntax: .Beep(freq, milliseconds)

Specifies how long in milliseconds to sound the computer’s speaker.

freq—Frequency of the sound, from 37–32,767 Hz. Default is 37Hz.

milliseconds—How long to sound speaker, in milliseconds (ms), beginning at 100ms (the default). Example: beep(1200, 150)

© SecureAgent Software, Tulsa OK USA. All rights reserved.AdminDriverAdd

[WinNT ONLY – Win9x always returns zero] The AdminDriverAdd function is used to install a new service onto the system.

RETNUM AdminDriverAdd(

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)

Parameters

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.

MsgFamily

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.

MsgPath

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”.

Returns

This function returns zero if the driver was installed or one if an error occurs.

Remarks

Please refer to Microsoft documentation for further information on any of these parameters.

© SecureAgent Software, Tulsa OK USA. All rights reserved.GetWebPage

The GetWebPage function is used to retrieve the contents of a Web page.

COUNT GetWebPage(“URL”,StemOutputList)

Parameters

URL

A Web page address to be retrieved, such as http://www.secureagent.com or http://www.secureagent.com/about.htm

StemOutputList

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.

Returns

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.GetSystemName

The GetSystemName function is used to retrieve the name of the computer on which the REXX program is executing.

COMPNAME GetSystemName(

)

Returns

This function returns an empty string if the computer name cannot be determined.

© SecureAgent Software, Tulsa OK USA. All rights reserved.GetIPList

The GetIPList function is used to retrieve a list of the network IP addresses of the computer on which the REXX program is executing.

COUNT GetIPList(

[Hostname,] // name of computer (optional)StemOutputList // the resulting list

)

Parameters

hostnameName of the computer on which the REXX program is executing.

StemOutputList

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.

Returns

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.



Functions: C

C2D C2X CallStack (stemvariable) Center (string,length[,pad]) or Centre Char (n) CoaxCommand (coaxid, text) CoaxGetCursor CoaxGetNextScreen CoaxGetScreen (coax, stem_name)

CoaxPress (‘COAXn’,’key’) CoaxSetCursor (‘COAX#’,row,col) CoaxText (‘COAX#’,text) Compare (string1,string2[,pad]) Copies (string,n)


Center Function

Syntax: Center(string,length[,pad]) or

Centre(string,length[,pad])

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Char Function

Syntax: CHAR(n)

Where n (0 to 255) is an ASCII character to be returned.

SAY CHAR(65)/* the letter A */

© SecureAgent Software, Tulsa OK USA. All rights reserved.CoaxCommand Function

Syntax: CoaxCommand(coaxid, text)

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.

Error -- 3270 controller failed to echo command correctly.Error -- miscellaneous, undefined.

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.CoaxGetScreen Function

Syntax: CoaxGetScreen(coax, stem_name)

This REXX function gets the coax screen data and stores it into the stem name.

Coax specifies the coax device number.

Stem_name specifies where to store the coax screen data. Example:

count = 0

x = coaxgetscreen(coax1, scrn)Do While count < scrn.0

count=count+1 Say scrn.count

End

© SecureAgent Software, Tulsa OK USA. All rights reserved.CoaxPress Function

Syntax: CoaxPress('COAXn','key')

The CoaxPress function allows you to press a specific key on the specified coax. COAXn must be COAX1, COAX2, COAX3, or COAX4. Valid keys are shown below:

Return Codes: 0=OK 1=coax not available 2=hung (undesired response) 3=unknown key

VALID 3178 KEYS VALID 3205 KEYS VALID 3180 KEYS(normal 3270 consoles) (IBM 43x1 service processor)(IBM 3090/9000 service processor)

attention backspace assign_console

backspace backtab backspacebacktab change_display backtabclear cmrq backwardcursor_select copy canceldelete delete cleardevice_cancel diagnostics deletedown down device_cancelduplicate enter downenter erase_eof enderase_eof erase_input entererase_input home erase_eoffast_left insert erase_inputfast_right interrupt fast_left

field_mark left fast_righthome Indsc forwardinsert mode_select homeleft newline indexmlt_jump pa1 insertnewline pa2 irpt

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

resetrightrstrtstartstopsvpceswap_consoletabtesttod_enableupview_log

Examples:/* The following example will press the enter key on a MVS console attached to COAX1.*/

x=CoaxPress('COAX1','ENTER')

/* The following example will press the tod enable key on an IBM 3090/9000 service processor console attached to COAX2. NOTE that 'COAX'CoaxNum is interpreted by REXX to be COAX2.*/

CoaxNum = 2x=CoaxPress('COAX'CoaxNum, 'TOD_ENABLE')

© SecureAgent Software, Tulsa OK USA. All rights reserved.CoaxSetCursor Function

Syntax: CoaxSetCursor('COAX#',row,col)

Position Cursor on screenReturn Codes 0=OK

1=coax not available2=coax not responding as desired (hung)3=bad row specified4=bad col specified

© SecureAgent Software, Tulsa OK USA. All rights reserved.CoaxText Function

Syntax: CoaxText('COAX#',text)

Text to type at cursor locationReturn Codes 0=OK

1=coax not available2=coax not responding as desired (hung)3=unknown characters

© SecureAgent Software, Tulsa OK USA. All rights reserved.Compare Function

Syntax: Compare(string1,string2[,pad])

Identical strings cause a "0" return value. Else, the character position of the first mismatch is returned. If one string is shorter, it will be padded on the right.

Compare('water fall','water fall') == 0Compare('water fall','waterfall') == 6Compare('parking','par','#') == 4

© SecureAgent Software, Tulsa OK USA. All rights reserved.Copies Function

Syntax: COPIES(string,n)

Replicates the string n (0 or more) times. If 0, a null string is returned.

Copies('do',5) == "dododododo"

SAY Copies('$ ',10)/* displays "$ $ $ $ $ $ $ $ $ $" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: D

D2C D2X DataType (string [, type]) Date ([option]) DateCalc ( ) Dec2Hex (n) Delstr (string,n[,length]) DelWord (string,n[,length]) Deq

DialPager (‘ComPort’,"Pager Phone No.’,’Calling Phone’ [,’Options’]) Digits

© SecureAgent Software, Tulsa OK USA. All rights reserved.DataType Function

Syntax: DataType(string [, type])

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:

x = datatype('12') = 2x = datatype(' ') = 3x = datatype('123*') = 3x = datatype('12.3', 'N') = 1x = datatype('12', 'W') = 0

x = datatype('Fred', 'M') = 1x = datatype(' ', 'M') = 0x = datatype('Minx', 'L') = 0x = datatype('3d?', 'S') = 1x = datatype('BCd3', 'X') = 1x = datatype('BC d3', 'X') = 1x = datatype('BCd3', 'A') = 1x = datatype('10011', 'B') = 1

© SecureAgent Software, Tulsa OK USA. All rights reserved.Date Function

Syntax: Date([option])

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]’

Date('N') == '1 Jan 1980'Date('C') == 29220Date('J') == 80001Date('M') == 'January'Date('S') == '19800101'

/* good for sorting */Date('U') == '01/01/80'Date('W') == 'Tuesday'

my_month = Date('M')/* example of use */

© SecureAgent Software, Tulsa OK USA. All rights reserved.DateCalc Function

Syntax: DateCalc( )

The date calculation function takes zero, one or two parameters. With no parameters it will return today's date in various formats all contained in one string as follows:

"MM/DD/YYYY JULIAN DAYNAME MONTHNAME DD YYYY DOC DM 36x D DDMonYYYY WKNo BASE"

Where: MM/DD/YYYY = date in US format

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Dec2Hex Function

Syntax: Dec2Hex(n)

Returns a string containing the hexadecimal equivalent of n with a leading zero if the first character would otherwise be in the range A-F.

Dec2Hex(254) /* returns "0FE" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.DelStr Function

Syntax: DelStr(string,n[,length])

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.

DelStr('Jersey City, NJ',4) == "Jer"DelStr('Armonk, NY',7,1) == "Armonk NY"DelStr('Vancouver, BC',14) == "Vancouver, BC"

© SecureAgent Software, Tulsa OK USA. All rights reserved.DelWord Function

Syntax: DelWord(string,n[,length])

Deletes words at a time. It is just like DELSTR except that it counts space-delimited words instead of characters.

DelWord('A third try',3) == "A third "DelWord('A third try',2,1) == "A try"

© SecureAgent Software, Tulsa OK USA. All rights reserved..DialPager

Syntax: .DialPager('ComPort','Pager Phone No.','Calling Phone' [,'Options'])

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.

Examples:x = DialPager("COM1", "555-1212", "1-918-234-9200")x = DialPager("COM1", "9 W 555-1212", "1-918-234-9200")x = DialPager("COM1", "P 555-1212", "1234 1-918-234-9200", "ATE1")(pulse mode)x = DialPager("COM1", "555-1212", "WWWWW1-918-234-9200")

Note: You do not need to put an @ sign between parts of the telephone number or a # sign after the caller’s return telephone number since these characters are built into the function.

The x return code will be one of the following:

Value Meaning 0 OK 1 CONNECT 2 RING 3 NO CARRIER

4 ERROR 6 NO DIALTONE 7 BUSY 8 NO ANSWER

© SecureAgent Software, Tulsa OK USA. All rights reserved.Enq and Deq Functions

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:

X=Deq(serializer name)

for example: X=Deq(task.1)

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: F

FileClose (str) FileExists (str) FileReceive (‘device’,’pc_file’,mainframefile’,’options’) FileSearch (filemask,stemname) FileSend (‘device’,’pc_file’,’mainframefile’,’options’)

FileSize (str)

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileClose Function

Syntax: FileCose(str)

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.

See also: Functions: F Built-In Functions

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileExists Function

Syntax: FileExists(str)

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileReceive Function

Syntax:FileReceive('DEVICE','PC_FILE','MAINFRAMEFILE','OPTIONS')


X=FileReceive('Coax#','PC-file',Mainframefile','CMS or TSO or CICS')

RECEIVE Options for TSO RECEIVE Options for CMS RECEIVE Options for CICS

© SecureAgent Software, Tulsa OK USA. All rights reserved.RECEIVE Options for TSO

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.RECEIVE Options for CMS

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.RECEIVE Options for CICS

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileSearch Function

Syntax: FileSearch(filemask,stemname)

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:

SV_0719.LOGAA_0719.LOGBB_0719.LOGCC_0719.LOGDD_0719.LOG

The results of the file search would be:

file_count == 5 (same as my_log.0)my_log.0 == 5 (same as file_count)my_log.1 == SV_0719.LOG

my_log.2 == AA_0719.LOGmy_log.3 == BB_0719.LOGmy_log.4 == CC_0719.LOGmy_log.5 == DD_0719.LOG

*/

Note: We suggest all NEW programs use the following overhead-reducing advanced method and where possible, convert the standard method to the advanced:

X=FileSearch('Filemask','Stemname')

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileSend Function

Syntax: FileSend('DEVICE','PC_FILE','MAINFRAMEFILE','OPTIONS')


X=FileSend('CoaxX','pc_file','Mainframefile','CMS' or 'TSO' or 'CICS')

OPTIONS for

- TSO

- CMS

- CICS

See also: Functions: F

© SecureAgent Software, Tulsa OK USA. All rights reserved.SEND Options for TSO

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.SEND Options for CMS

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.

Return to FileSend Function

© SecureAgent Software, Tulsa OK USA. All rights reserved.SEND Options for CICS

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.

Return to FileSend Function

© SecureAgent Software, Tulsa OK USA. All rights reserved.FileSize Function

Syntax: FileSize(str)

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!

© SecureAgent Software, Tulsa OK USA. All rights reserved.Hex2Dec

Syntax: Hex2Dec(str)

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.

SAY Hex2Dec('A2BF')/* Displays "41663" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: I

InputBox (‘message-text’,’varname’[,[field-length][,[‘title’]]]) InputBoxPassword Insert (new,destination[,[n][,length][,pad]]]) IssueCommand

© SecureAgent Software, Tulsa OK USA. All rights reserved.InputBox Function

Syntax: InputBox('message-text','varname'[,[field-length][,['title']]])

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).

RETURN CODES

CANCEL 0OK 1

Examples

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')

© SecureAgent Software, Tulsa OK USA. All rights reserved.Insert Function

Syntax: Insert(new,destination[,[n][,length][,pad]]])

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.

Insert('wall','paint') == "wallpaint"Insert(' to','wallpaint, 4,6,'-' == "wall to---paint"Insert('paste','white',7) == "white paste"

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: L

LastPos (sub_str,main_str[,start]) Left (string,length[,pad]) Length (string) LineIn (name) LineOut (name[,string]) ListHostGlobals ListNodeGlobals LogSwitch (Host [,option])

© SecureAgent Software, Tulsa OK USA. All rights reserved.LastPos Function

Syntax: LastPos(sub_str,main_str[,start])

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.

LastPos('rk','stark park in the dark') == 21

© SecureAgent Software, Tulsa OK USA. All rights reserved.Left Function

Syntax: Left(string,length[,pad])

Will return length characters starting from the left end of string. If the source string is shorter than length, the remaining spaces are padded.

Left('-xyz',10,'$') == "-xyz$$$$$$"Left('AEIOU',3) == "AEI"

© SecureAgent Software, Tulsa OK USA. All rights reserved.Length Function

Syntax: Length(string)

The number of characters comprising the string is returned.

school = 'elementary'Length(school) == 10

© SecureAgent Software, Tulsa OK USA. All rights reserved.LineIn Function

Syntax: LineIn(name)

Where name is the name of the text 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'). Returns a string containing the current line

from the specified text file. Each call to LineIn returns the next line from the file. Blank lines are skipped.

When the end of the file is reached or a DOS error occurs, a null string is returned.

© SecureAgent Software, Tulsa OK USA. All rights reserved.LineOut Function

Syntax: LineOut(name[,string])

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 */


LogSwitch Function

Syntax: LogSwitch(Host [,option])

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.

Example:

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: M

Max (numlist) MassageBox (message-text[,[title][,[buttons][,[icon]]]]) Min (numlist) Msg

© SecureAgent Software, Tulsa OK USA. All rights reserved.Max Function

Syntax: Max(numlist)

Will return the largest value from a list of one or more numbers.

Max(2,4,6,88,7,5,3,-1)== 88

© SecureAgent Software, Tulsa OK USA. All rights reserved.MassageBox Function

Syntax: MessageBox(message-text[,[title][,[buttons][,[icon]]]])

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:

MessageBox('Sample Text',,'QUESTION')

Button Provides Message Box with

ABORTRETRYIGNORE 3 buttons: ABORT, RETRY, IGNOREOK 1 button: OKOKCANCEL 2 buttons: OK, CANCEL. RETRYCANCEL 2 buttons: RETRY, CANCELYESNO (default) 2 buttons: YES , NOYESNOCANCEL 3 buttons: YES, NO, CANCEL

Return Codes:IGNORE 0NO 0OK 1YES 1RETRY 1ABORT 2CANCEL 2

ICON Definition

EXCLAMATION or ! Provides a message box with the "!" icon

INFORMATION or i Provides a message box with the "i" iconQUESTION or ? Provides a message box with the "?" iconSTOP Provides a message box with the stop sign icon. DEFAULT ICON

Examples:

To produce a message box with the text of "Test MessageBox", two buttons (YES and NO), and the stop sign icon:

x=MessageBox('Test MessageBox')

To produce a message box with the text of "Test MessageBox", title of "Message Box Title", three buttons (ABORT, RETRY, and IGNORE), and the icon of question:

x-MessageBox('Test MessageBox','Message Box Title','ABORTRETRYIGNORE','QUESTION')

To produce a message box with the text of "Test MessageBox", the default title, the default buttons, and the exclamation icon:

x-MessageBox ('Test MessageBox',,,'!')

© SecureAgent Software, Tulsa OK USA. All rights reserved.Min Function

Syntax: MIN(numlist)

Will return the lowest value from a list of one or more numbers.

Min(2,4,-6,88,7,5,3,-1)== -6

© SecureAgent Software, Tulsa OK USA. All rights reserved.Overlay

Syntax: Overlay(new,destination[,[n][,[length][,pad]]])

This function is exactly like the Insert function except that existing characters in the destination string are overwritten by the new string.

Overlay('x','wallpaper',4,5,'!')== "walx!!!!r"

© SecureAgent Software, Tulsa OK USA. All rights reserved.Pos

Syntax: Pos(sub_str,main_str[,start])

This is just like the LastPos function except that it searches forward from either the (default) beginning of the string or a specified position.

Pos('rk','Stark park in the dark',6) == 9

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: R

Random Reboot ReceiveFile RecordIn (name,[rec#],recsize) RecordOut (name,string[,[rec#],[recsize][,pad]) Reverse (string) Right (string,length[,pad])

© SecureAgent Software, Tulsa OK USA. All rights reserved.RecordIn Function

Syntax: RecordIn(name,[rec#],recsize)

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.RecordOut Function

Syntax: RecordOut(name,string[,[rec#],[recsize][,pad])

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 */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Reverse Function

Syntax: Reverse(string)

The order of the string is reversed.

Reverse('B12345x')== "x54321B"Reverse('RETUPMOC')== "COMPUTER"

© SecureAgent Software, Tulsa OK USA. All rights reserved.Right Function

Syntax: Right(string,length[,pad])

Will return length characters starting from the right end of string. If the source string is shorter than length, the remaining spaces are padded.

Right('-xyz',10,'$')== "$$$$$$-xyz"Right('AEIOU',3)== "IOU"

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: S

Sam_Alert Send SendFile SendMail SendSNMPTrap SetComPort (‘ComPort’ [, ‘Baud Rate’] [, ‘DataBit’] [, ‘StopBit’] [, ‘Parity’]) SetCurrentHost (host) SetCursor

SetHostName (hostid, text) SetKeyGroup (keygroup, option) ShellCommand Sign (number) SourceLine Space (string[,[n][,pad]]) Speak Sql_AddColumn (DatabaseID,"TableName","ColumnName","DataType")

Sql_AddEntry (DatabaseID,"TableName","Values") Sql_CloseDatabase (DatabaseID) Sql_CreateTable (DatabaseID,"TableName","ColumnNameAndInfo") Sql_DeleteColumn (DatabaseID,"TableName","ColumnName") Sql_DeleteEntry (DatabaseID,"TableName","Entry") Sql_DeleteTable (DatabaseID,"TableName")

Sql_GetColumns (DatabaseID,"TableName","Stem") Sql_GetEntries (DatabaseID,"TableName","ColumnName(s)","EntriesStem"[,"SortStatement"][,"Delimiter"]]) Sql_GetErrorMessage ("ErrorString") Sql_GetTables (DatabaseID,"TablesStem"[,"Wildcard"]) Sql_IssueStatement (DatabaseID,"SqlStatement")

Sql_IssueStatementAndGetResults (DatabaseID,"SqlStatement","FieldsStem","RowsStem","Delimiter") Sql_OpenDatabase ("DatabaseName"[,"UserID","Password"]) Sql_RenameColumn (DatabaseID,"TableName","OriginalColumnName","NewColumnName","DataType") Sql_RenameTable (DatabaseID,"OriginalTableName","NewTableName") StartScript (ScriptName)

StatusDisplay (stream[,operation[,streamcommand]]) Strip (string[,[option],[char]]) StrLwr (str) StrUpr (str) SubStr (source,n[,[length][,pad]]) SubWord (source,n[,length]) SVAttach SVClearLogs

SVConnect SVDetach SVDisconnect SVMenu (menu, item)

SVScheduleAdd ("session_name", "command_text", "date/time"’[, "RepeatType", "RepeatValue"]) SVScheduleDisable (ID#) SVScheduleEnable (ID#)

SVScheduleList (list_stem_name[,session_name_filter]) SVScheduleRemove (ID#) SVT_Dial (number_to_dial) SVT_GetDigits (how_many_digits) SVT_HangUp SVT_Init (channel_to_use) SVT_Play SVT_Record (filename)

SVT_Speak (text_to_speak) Symbol (symbol_string)

© SecureAgent Software, Tulsa OK USA. All rights reserved.SetComPort Function

Syntax: SetComPort('ComPort' [, 'Baud Rate'] [, 'DataBit'] [, 'StopBit'] [, 'Parity'])

Allows the user to specify a com port and additional option are the baud rate, data bit, stop bit and parity. If these are not specified, the function will use the default setting of 2400, 7, 1, even.

ComPort: Specify which com port the modem is connected to.Baud Rate: Specify the baud rate at which the modem operates. Recommend using 9600 or 2400

baud depending on pager service.

Data Bit: Specify number of bits in the bytes transmitted and received.

Four (4) through eight (8) bits.

Stop Bit: Specify the number of stop bits to be used.

This member can be one of the following values:

Value Meaning

0 1 stop bit 1 1.5 stop bits2 2 stop bits

Parity: Specify the parity scheme to be used. This member can be one of the following values:

Value Meaning

0 none 1 odd 2 even 3 mark 4 space

Examples:

x = SetComPort("COM1", 2400, 7, 0, 2)

The x return code will either be 0 for a good return or else an error number.

See also: Functions: S Built-In Functions

© SecureAgent Software, Tulsa OK USA. All rights reserved.SetCurrentHost Function

Syntax: SetCurrentHost(host)

This REXX function sets the host specified to the current or active host.

Host specifed hosts S, A – P (or host name)

Example:

x = setcurrenthost(‘B’)

© SecureAgent Software, Tulsa OK USA. All rights reserved.SetHostName Function

Syntax: SetHostName(hostid, text)

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.

See also: Functions: S

Built-In Functions

© SecureAgent Software, Tulsa OK USA. All rights reserved.SetKeyGroup Function

Syntax: SetKeyGroup(keygroup, option)

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.

Return codes:

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.)


SIGN Function

Syntax: SIGN(number)

Will return a value signifying the sign of a number. Negative returns a "-1". Positive returns a "1". Zero returns a "0".

SIGN(200) == 1SIGN('00000')== 0

© SecureAgent Software, Tulsa OK USA. All rights reserved.Space Function

Syntax: Space(string[,[n][,pad]])

Standardizes the spacing of blank delimited words in string by removing any trailing and leading spaces and either removing spaces and/or adding pad. The default value of n is "1".

/* examples of the SPACE function */

Space(' Once upon a time ')== "Once upon a time"Space(' con cat en ate ',0)== "concatenate"Space(' con cat en ate ',2,'-')== "con--cat--en—ate

© SecureAgent Software, Tulsa OK USA. All rights reserved.Strip Function

Syntax: Strip(string[,[option],[char]])

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.

/* examples of the STRIP function */

Strip(' paint ')== "paint"Strip(' Wire ','t')

== " Wire"Strip('**furniture**','L','*')== "furniture**"

© SecureAgent Software, Tulsa OK USA. All rights reserved.StrLwr Function

Syntax: StrLwr(str)

Returns a string containing str with all uppercase characters converted to lowercase.

SAY StrLwr('high ASCII')/* Displays "high ascii" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.StrUpr Function

Syntax: StrUpr(str)

Returns a string containing "str" with all lowercase characters converted to uppercase.

SAY StrUpr('low ASCII')/* Displays "LOW ASCII" */

© SecureAgent Software, Tulsa OK USA. All rights reserved.SubStr Function

Syntax: SubStr(source,n[,[length][,pad]])

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.

SubStr('123abc',3)== "3abc"SubStr('123abc',3,7,'*')== "3abc***"

© SecureAgent Software, Tulsa OK USA. All rights reserved.SubWord Function

Syntax: SUBWORD(source,n[,length])

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.

/* example of the SubWord function */

SubWord('Four hundred and seven ',3)

== "and seven"

© SecureAgent Software, Tulsa OK USA. All rights reserved.SVMenu Function

Syntax: SVMENU(menu, item)

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).

© SecureAgent Software, Tulsa OK USA. All rights reserved.Symbol Function

Syntax: SYMBOL(symbol_string)

Provides a way to test the validity or value type of a symbol string.

If symbol_string belongs to a variable, the function returns "VAR". If it is a literal constant or a valid uninitialized symbol, it returns "LIT". If not a valid symbol, it returns "BAD".

A symbol_string which is used as a variable name should be between quotes or apostrophes so that any initialized value is not accidentally evaluated.

a=33/* assign value to variable */Symbol(a) == LIT

/* left out apostrophes - evaluated to 33 */Symbol('A') == VAR /* now it understands */Symbol('*+*') == BAD /* invalid symbol */

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: T

Time ([option]) Tn3270Connect (‘SessionName’,‘Target_IP’,‘LU_Name’,ModelNumber,‘VisaraIndicator’) Trace TraceRoute Translate (stem, string [, tableo][, tablei][,pad]) Trunc TwinaxGetCursor

TwinaxGetNextScreen TwinaxGetScreen (twinax, stem_name)

TwinaxPress (‘TWINAXn’,’key’) TwinaxSetCursor (‘TWINAX#’,row,col) TwinaxText (‘TWINAX#’,text) TypeText

© SecureAgent Software, Tulsa OK USA. All rights reserved.Time Function

Syntax: Time([option])

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 */

See also: Functions: T Built-In Functions


Translate Function

Syntax: Translate(stem, string [, tableo][, tablei][, pad])

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)

Examples:

x = translate('tmp', 'abcdef') = tmp.1 = ‘ABCDEF’x = translate('tmp', 'abbc', '&', 'b') = tmp.1 = ‘a&&c’x = translate('tmp', 'abcdef', '12', 'ec') = tmp.1 = ‘ab2d1f’x = translate('tmp', 'abcdef', '12', 'abcd', '.') = tmp.1 = ‘12..ef’x = translate('tmp', '4123', 'abcd', '1234') = tmp.1 = ‘dabc’ NOTE: x returns a zero.

© SecureAgent Software, Tulsa OK USA. All rights reserved.TwinaxGetScreen Function

Syntax: TwinaxGetScreen(twinax, stem_name)

This REXX function gets the twinax screen data and stores it into the stem name.

Twinax specifies the twinax device number.

Stem_name specifies where to store the twinax screen data.

Example:

count = 0x = twinaxgetscreen(twinax1, scrn)Do While count < scrn.0

count=count+1 Say scrn.count

End

© SecureAgent Software, Tulsa OK USA. All rights reserved.TwinaxPress Function

Syntax: TwinaxPress('TWINAXn','key')

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)

3=unknown key

VALID 5250 KEYSAttention Backspace Backtab ClearCommand Delete Down Duplicate

Enter Erase_input Fast_left Fast_rightField_exit Field_minus Field_plus HelpHome Insert Internal_jump JumpLeft Newline Pf1 Pf2Pf3 Pf4 Pf5 Pf6Pf7 Pf8 Pf9 Pf10Pf11 Pf12 Pf13 Pf14Pf15 Pf16 Pf17 Pf18Pf19 Pf20 Pf21 Pf22Pf23 Pf24 Print ResetRight Roll_down Roll_up

System_requestTab Test Up

Examples:

/* The following example will press the enter key on an OS/400 console attached to TWINAX1.*/

x=TwinaxPress('TWINAX1','ENTER')

© SecureAgent Software, Tulsa OK USA. All rights reserved.TwinaxSetCursor Function

Syntax: TwinaxSetCursor('TWINAX#',row,col)

Position Cursor on screenReturn Codes

0=OK1=twinax not available2=twinax not responding as desired (hung)3=bad row specified4=bad col specified

© SecureAgent Software, Tulsa OK USA. All rights reserved.TwinaxText Function

Syntax: TwinaxText('TWINAX#',text)

Text to type at cursor locationReturn Codes

0=OK1=twinax not available2=twinax not responding as desired (hung)3=unknown characters

© SecureAgent Software, Tulsa OK USA. All rights reserved.Verify

Syntax: Verify(string, reference [, option][, start])

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).

Examples: x = verify('123', '1234567890') = 0

x = verify('1Z3', '1234567890') = 2x = verify('AB4T', '1234567890', 'M') = 3x = verify('1P3Q4', '1234567890', , 3) = 4x = verify('ABCDE', '', , 3) = 3x = verify('AB3CD5', '1234567890', 'M', 4) = 6

© SecureAgent Software, Tulsa OK USA. All rights reserved.Functions: W

Word (string,n) WordIndex (string,n) WordLen WordLength (string,n) WordPos (phrase,string[,start]) Words (string) Write2Com ("Com Port", "ASCII string")

© SecureAgent Software, Tulsa OK USA. All rights reserved.Word Function

Syntax: Word(string,n)

Same as SubWord(string,n,1). Will return just one word from word position n in the string.

Word('Four hundred and seven',3) == 'and'

© SecureAgent Software, Tulsa OK USA. All rights reserved.WordIndex Function

Syntax: WordIndex(string,n)

The character position of string's nth word. If n exceeds the actual number of space delimited words, a "0" is returned.

WordIndex('123 567 ABC',3)== 9


WordLength Function

Syntax: WordLength(string,n) The length of word n in string is returned. Should n exceed the actual number of space delimited words, a "0" is returned.

WordLength('Four hundred and seven',2)== 7

© SecureAgent Software, Tulsa OK USA. All rights reserved.WordPos Function

Syntax: WordPos(phrase,string[,start])

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

© SecureAgent Software, Tulsa OK USA. All rights reserved.Words Function

Syntax: Words(string)

Examines string and returns the count of space-delimited words.

Words('We also have 2 fax/modems.') == 5

© SecureAgent Software, Tulsa OK USA. All rights reserved.Write2Com Function

Syntax: Write2Com("Com Port" , "ASCII string")

This function writes ASCII characters out to the specified com port.

Com Port specified com port.ASCII string any ASCII string characters.

Example:

x = Write2Com("com1", "Hello World, Welcome to SuperVision") Note: Recommend calling the REXX function "setcomport()" first to set up the com port.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parsing for ARG and PARSE

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

© SecureAgent Software, Tulsa OK USA. All rights reserved.Elementary Parsing

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Comma as a Literal String

/* 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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Parsing by an Exact Character Position

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Using PARSE ARG in the Destination Routine

Finally, this same template could be used after invoking a routine by using PARSE ARG in the destination routine.

parse upper arg star 2 x1 '-' . b2 .

Another use is just to find out what the system time is:

/*ask for time*/'ZDSYS'/*get status string*/PARSE MSG.. curr_time/*put third string into a local variable and discard the rest*/SAY 'The system time is' curr_time

© SecureAgent Software, Tulsa OK USA. All rights reserved.REXX Arithmetic

REXX supports 32-bit integer arithmetic. A numeric value is any continuous string of decimal digits zero through nine (0-9). There may be a sign prefix as part of the string.

/* valid numbers */123/* a simple, 3 digit value */

+45/* a positive signed number */-789/* a negative signed number */2400000000/* 2.4 billion */

The two types of errors which may occur are related to either insufficient storage for an intermediate or final value and to arithmetic underflow or overflow by the processor.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Input and Output in REXX

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Reserved Keywords

There are only reserved symbols in REXX. A programmer may indeed wish to create a label or variable using what should normally be regarded only as a keyword or instruction. For example:

/* example 1: keyword used as a label */

exit:/* EXIT as a label */ SAY 'End of program' EXIT/* Terminate routine */

/* example 2: keyword as a label and as a simple variable */

return:/* keyword as label */

return = 'Sunday night before 10'/* using keyword to hold string */ SAY return/* display a frequent time slot */

RETURN/* return to calling routine */

/* example 3: keyword being used as a variable and stem name */

/* initialize simple variable and compound variables */say = 0 ; say.0 = 0 ; say.1 = 10 ; say.2= 20 ;SAY say.say say.1 say.2/* displays "0 10 20" */

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.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Special Variables

The implementation of REXX has two special variables that can be set during program execution.

RC The Return Code is set by any command to the host environment.

RESULT Is only set by a subroutine's RETURN instruction and contains any expression that may

have accompanied the RETURN. A RETURN without an expression is the same as a DROP RESULT.

As with keywords, these variables may be used for other purposes but will be reset by the RETURN instruction and lose whatever value may have been assigned to them.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Using the REXX Editor

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

Displaying Windows

© SecureAgent Software, Tulsa OK USA. All rights reserved.Create a New REXX File

1 To create a new REXX file (*.rex):

1. Select File from the program menu bar, and New from the drop-down menu that appears, or2. Press the New File button

© SecureAgent Software, Tulsa OK USA. All rights reserved.Open an Existing REXX File

1 To open an existing REXX file (*.rex):

1. Select File from the program menu bar, and Open from the drop-down menu that appears, or2. Press the Open File button

© SecureAgent Software, Tulsa OK USA. All rights reserved.Save the File

1 To save a REXX file (*.rex):

1. Select File from the program menu bar, and Save from the drop-down menu that appears, or2. Press the Save File button

Selecting the Save option will automatically update the file for the active window, while selecting Save As allows the user to name a file and chose the destination BEFORE writing information to disk.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Cut Highlighted Text

1 To cut a string of highlighted text:

1. Select Edit from the program menu bar, and Cut from the drop-down menu that appears, or2. Press the Cut Highlighted Text button

The text that has been cut may now be pasted into a different position, or a different file.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Copy Highlighted Text

1 To copy a string of highlighted text:

1. Select Edit from the program menu bar, and Copy from the drop-down menu that appears, or

2. Press the Copy Highlighted Text button

The text that has been copied to the clipboard may now be pasted into a different position, or a different file.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Paste Highlighted Text

1 To paste a string of highlighted text that has been cut or copied :

1. Place the cursor at the position where text should be added.2. Select Edit from the program menu bar, and Paste from the drop-down menu that appears, or3. Press the Paste Highlighted Text button

© SecureAgent Software, Tulsa OK USA. All rights reserved.Print a Window

1 To print the ACTIVE file window :

1. Select File from the program menu bar, and Print from the drop-down menu that appears, or2. Press the Print Window button

© SecureAgent Software, Tulsa OK USA. All rights reserved.REXX Editor Options

Line Number on Printing Make Current Font Sizes Default Select Color Setup Set Display Font Size Set Printing Font Size Status Bar Syntax Colorization Toolbar

© SecureAgent Software, Tulsa OK USA. All rights reserved.Line Number on Printing

When enabled, this option provides corresponding line numbers on the print out of the ACTIVE file window.

1 To enable or disable this option :

1. Select Options from the program menu bar2. Select Line Number on Printing from the drop-down menu that appears.

A checkmark to the left of the option indicates enabled, while the absence of the checkmark indicates disabled.

© SecureAgent Software, Tulsa OK USA. All rights reserved.Make Current Font Sizes Default

When enabled, this option automatically establishes the selected display and printing font sizes as the default settings of the ACTIVE file window.


1. Select Options from the program menu bar2. Select Make current font sizes default from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Select Color Setup

When enabled, this option provides access to the following color sets of the ACTIVE file window: Default Black, Default White, Custom, and Define Custom.


1. Select Options from the program menu bar

2. Select Select Color Setup from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Set Display Font Size

When enabled, this option yields a menu that allows the user to select font size for text displayed in the ACTIVE file window.


1. Select Options from the program menu bar2. Select Set Display font size from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Set Printing Font Size

When enabled, this option yields a menu that allows the user to select font size for printing text in the ACTIVE file window.


1. Select Options from the program menu bar2. Select Set Printing font size from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Status Bar

When enabled, this option allows the status bar to be displayed at the bottom of the ACTIVE file window. The bar displays the line and column number associated with cursor placement in the document.


1. Select Options from the program menu bar2. Select Status bar from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Syntax Colorization

When enabled, this option will cause strings of text, in the ACTIVE file window, to be displayed in their assigned color.

1 To enable or disable this option:

1. Select Options from the program menu bar2. Select Syntax Colorization from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Toolbar

When enabled, this option will cause the REXX Editor Toolbar to be displayed at the top of the ACTIVE file window.


1. Select Options from the program menu bar2. Select Toolbar from the drop-down menu that appears.


© SecureAgent Software, Tulsa OK USA. All rights reserved.Displaying Windows

1 To duplicate the active window:

1. Select Window from the program menu bar, and New Window from the drop-down menu that appears.

1 To cascade diagonally all open windows:

1. Select Window from the program menu bar, and Cascade from the drop-down menu that appears.

1 To tile horizontally all open windows:

1. Select Window from the program menu bar, and Tile Horizontally from the drop-down menu that appears.

1 To tile vertically all open windows:

1. Select Window from the program menu bar, and Tile Vertically from the drop-down menu that appears.


Documents

Basic REXX