|
|
label
Entry of a symbolic address for the first command in the macro expansion (optional).
cmd-buff-addr
Address of a reference list which, in turn, also contains addresses which point, amongst others, to the command string. This list must commence on a full word boundary. Its detailed structure is described below.
Instead of a symbolic address it is possible to specify, enclosed in brackets, the number of a register which contains this address. Registers 2 through 12 may be used for this purpose.
msg-buffer
Address of a buffer for the messages or for information passed back to the program. -+--+--+--+--+--+--+--+--+--+--+- - - - -+- | lp | . . . | -+--+--+--+--+--+--+--+--+--+--+- - - - -+- After the macro OPENFT has been executed this buffer has the following contents: -+--+--+--+--+--+--+- - - -+--+--+- - - -+- - - | lp | lm | lm1 | msg1 | lm2 | msg2 | -+--+--+--+--+--+--+- - - -+--+--+- - - -+- - - | |
lp | Length field of 2 bytes. Contains the length of the buffer in bytes (including the length |
lm
Length field of 2 bytes. Before a command is executed, this field must contain the value X'0000'. After the execution of a command, this field contains the length of the returned text strings in bytes, excluding the lengths of the length fields lp and lm, but including the lengths of length fields lm1, lm2, etc. If the total length of the text strings to be delivered is greater than the buffer provided, then firstly a return code of '10' (hexadecimal) is passed back to the program and the field "lm" contains the length in bytes necessary to accommodate the full text.
lm1
Length field of 2 bytes. Contains the length of the message text msg1 in bytes, excluding the length of this length field.
msg1
This field contains the first line of the message text output to the terminal as a result of executing the command.
lm2
Length field of 2 bytes. Contains the length of the message text msg2 in bytes, excluding the length of this length field.
msg2
This field contains the second line of the message text output to the terminal as a result of executing the command.
In this way all the lines of the message text are output to the buffer, until either the message text has been output in full or until the buffer length lp has been reached. The last line output to the buffer is then possibly incomplete. Although in this instance no further lines are output to the buffer, the value for "lm" continues to be accumulated, so that eventually lm contains the size which would need to be defined as the buffer size (lp) in order to accept the output in full (excluding the length of the two length fields lp and lm).
The size of the output buffer should be adapted to approximately the volume of expected data. 200 bytes are sufficient to issue an NCOPY while approximately 8KB are required for an FTSHWLOG with 100 logging records.
The format of the messages is identical to those output on the terminal, i.e. if necessary, they contain control characters. These messages are described in the manual "openFT (z/OS) - Installation and Operation".
Instead of a symbolic address it is possible to specify, in brackets, the number of a register that contains this address. Registers 2 through 12 may be used for this purpose.
VERS=
The return codes have been changed in V10.0 of openFT. This means that different message numbers are output compared with previously (openFT <= V9.0). The VERS parameter is used to maintain compatibility with older programs:
1: The old return codes are output, default.
2: The new return codes are output.
The VERS parameter allows you to choose between old and new return codes for output:
If you require the old return codes to be output (default), compatibility with older programs is maintained. This means that they can be used unchanged and do not even need to be recompiled.
If you wish to use the new return codes, you must set the parameter VERS=2 explicitly, adapt the programs and recompile them.
Structure of the reference list (cmd-buff-addr)
The parameter cmd-buff-addr points to a list, the structure of which is described below.
Transfer of a user command
In the case where a user command is transferred via the macro OPENFT, the parameter cmd-buff-addr contains the address of a list which is four full words in length and corresponds to the "command processor parameter list" (CPPL) in TSO:
-+--+--+--+--+-
cmd-buff-addr ==> | CPPLCBUF |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+-
| Nullpointer |
-+--+--+--+--+--
| -
This field CPPLCBUF contains the address of the command buffer. The command buffer to which the address in field CPPLCBUF points must commence on a full word boundary and have exactly the same structure as for a TSO command processor.
-+--+--+--+--+--+--+--+--+--+--+- - - -+-
CPPLCBUF ==> | lng | off | command string . . . |
-+--+--+--+--+--+--+--+--+--+--+- - - -+-
lng
Length field of 2 bytes. This field contains the length of the command string plus the length of fields lng and off (thus, command string + 4).
off
Offset field of 2 bytes. This field contains the offset of the first parameter relative to the start of the command string (not relative to the start of this buffer).
command string
This field contains the command to be executed; it is held as a character string. The length of this string is limited to a maximum of 2000 characters. The commands are described in the chapter “openFT commands”.
A return code is sent to the application program in register 15 (right-aligned). Return code (hexadecimal) in R15:
'00' | Normal termination |
'04' | Warning |
'0C' | Syntax error, access conditions invalid |
'10' | The buffer was too small for the return message, the text was truncated. |
'12' | The resources (e.g. VTAM connection) are occupied. |
Example of calling a user command
The following NCOPY command is to be executed (using the new return codes):
|
|
The following ASSEMBLER code is required to effect it:
LA 13,SAVAREA SET UP SAVE AREA
OPENFT CMD=CMDBUFF,MSG=MSGBUFF,VERS=2
.
.
CMDBUFF DC A(CBUFF) ADDR OF COMMAND BUFFER
DC A(0) NOT USED
DC A(0) NOT USED
DC A(0) NOT USED
SPACE
CBUFF DS 0F COMMAND BUFFER
DC Y(CLNG) LENGTH FIELD
DC Y(L'CNAME) OFFSET TO 1ST. PARAMETER
CNAME DC C'NCOPY ' COMMAND NAME
DC C'TRANS=TO' 1ST. PARAMETER
DC C',PARTNER=BS2' 2ND. PARAMETER
DC C',LOC=(' LOCAL PARAMETER
DC C'FILE=DAT' FILE NAME
DC C',TRANS=('
DC C'BERT,A1234,PASSWORD' TRANSFER ADMISSION
DC C')),'
DC C'REM=*BS2000(' REMOTE PARAMETER
DC C'INFO' FILE NAME
DC C',TRANS=('
DC C'FRED,4567ABC,''COVERT''' TRANSFER ADM.
DC C'))'
CBFFEND EQU *
CLNG EQU CBFFEND-CBUFF BUFFER LENGTH
SPACE
MSGBUFF DS 0F MESSAGE BUFFER
DC Y(MSGLNG) BUFFER LENGTH
DC X'0000'
DS CL200 MESSAGE TEXT
MSGEND EQU *
MSGLNG EQU MSGEND-MSGBUFF
SPACE
SAVAREA DC 18F'0' SAVE AREA