USTBATCH Parameter Reference
USTBATCH Parameter | Range | Default | Description |
APPLPREF | 1-5 characters | UPSTR | Specifies the five character prefix USTBATCH will use to build it's own VTAM APPLID value; it will append a character-numeric value beginning at “001” to the specified APPLPREF value and use the resulting name to attempt to open a VTAM ACB with this name as the APPLID, incrementing the number until it finds a free VTAM application ID. |
APPLRETRY |
|
| This parameter is used if USTBATCH cannot find a free VTAM application ID (see APPLPREF= above). It will wait 5 seconds and try again, repeating this until an application ID is found free or the APPLRETRY limit is reached. The default is 240 which will cause USTBATCH to retry every 5 seconds for about 20 minutes. |
COMMAND |
| none | specifies an FDR/UPSTREAM-MVS console command. Do not include the "F UPSTREAM," preceding the command a you would from a console. |
CONV | “NONE”, “KEEP”, or “WAIT” | “NONE” | CONV= controls how USTBATCH manages its VTAM APPC conversation with the FDR/UPSTREAM-MVS main online task, and also that of the SNA or TCP/IP connection to the target workstations. USTBATCH always establishes a APPC connection to the main task for each requested operation in its input stream and transmits the request (target workstation and related parameters). The main task then initiates a APPC or TCP/IP conversation with the workstation and forwards the request. CONV= controls what happens next. CONV=NONE - causes the workstation to disconnect as soon as the request has been accepted by the FDR/UPSTREAM Started Task. The Started Task informs USTBATCH that the request was accepted or not, and USTBATCH itself disconnects and goes on to process its next request or terminate. The workstation will reconnect to FDR/UPSTREAM-MVS to perform the requested function, but USTBATCH cannot tell if the request was successful, only that it was accepted by the workstation. CONV=KEEP causes FDR/UPSTREAM-MVS to use the same conversation with the workstation for processing the request as was used to send the request to the workstation. In other words, FDR/UPSTREAM-MVS connects to the workstation, sends the request, and keeps that connection to process the request. USTBATCH will be notified as soon as the workstation begins processing the request at which point it will disconnect and process its next request. Certain parameter errors (such as invalid file specs) which prevent the request from ever being processed will be logged by the main task and by USTBATCH) with CONV=KEEP but will be recorded only at the workstation with CONV=NONE. CONV=WAIT includes the effect of CONV=KEEP, but in addition USTBATCH will itself remain connected to the FDR/UPSTREAM-MVS main task until the workstation completes the requested operation. At the completion of the operation, USTBATCH will log the final return code and FDR/UPSTREAM-MVS messages associated with the workstation operation, so that the success or failure of the operation can be determined from the USTBATCH log. If WTOCOMP is also specified, the return code will be logged on the system console as well as in the USTBATCH log. CONV=WAIT causes USTBATCH to maintain 2 internal queues of requests. All the requests in the USTBATCH input will be parsed and added to a "wait" queue, ready for initiation. USTBATCH will attempt to initiate concurrent requests to multiple workstations, keeping as many workstations busy as possible. Once a request has been successfully initiated, it is transferred to an "active" queue to await notification of its completion. CONV=WAIT also enables USTBATCH to accept console commands which can be used to display USTBATCH status and modify its operation. If CONV=KEEP or WAIT is specified, you should be wary of also specifying QUEUE; if the workstation operation cannot be immediately started and must be queued, USTBATCH will wait until the request can finally be processed. |
DNSNAME | n/a | n/a | Identifies the target workstation using a Domain Name Server (DNS). It specifies the DNS name of the target workstation (up to 63 characters). If used, the USTBATCH JCL must contain a SYSTCPD DD statement pointing to a valid TCPDATA file or member. |
ENDPARM | n/a | n/a | This optional keyword indicates the end of all USTBATCH keywords for this execution of USTBATCH. Any parameters specified after the ENDPARM keyword receive and error message and are ignored. |
LOGMODE | 1-8 characters | #INTER | Specifies the VTAM logon mode entry name which will be used by the FDR/UPSTREAM-MVS on-line task to establish a session to all VTAM APPC target workstations (TARGLU= or TARGNAME= when the connection is SNA) requested by this USTBATCH execution. It will also be used by the workstation when it establishes its session back to FDR/UPSTREAM-MVS to perform the requested function. It is not used for TCP/IP targets (TCPTARG= or TARGNAME= when the connection is TCP/ IP). Unlike the other "single-use" parameters, LOGMODE= may actually appear more than once. If it is placed in the beginning of the USTBATCH input, with the other "single-use" parameters, it will be used for all sessions established by USTBATCH (unless overridden later in the input). LOGMODE= may also appear after a TARGLU= or TARGNAME= parameter; if so, it's value will be used for that session and all sessions that follow it unless overridden by another LOGMODE=. Luckily, the default of #INTER is usually correct for all sessions, so LOGMODE= will usually not have to be specified at all. |
MAXRETRY | 0 - 255 | 0 | Specifies the maximum number of retry attempts the FDR/UPSTREAM-MVS on-line initiator will attempt prior to returning an “LU NOT AVAILABLE” indication to the USTBATCH utility. If the value is non-zero and the initial attempt to initiate a conversation with the workstation is unsuccessful, USTBATCH will retry the conversation to the workstation every ten (10) minutes decrementing the retry count until it reaches zero. At that time, an “LU NOT AVAILABLE” indication will be sent to the USTBATCH utility task. The default is 0 (zero). |
QUEUE | n/a | Not specified | Specification of this parameter instructs the target workstation to queue the request if possible in the event it is unable to process it immediately. If not specified, requests will not be queued. QUEUE should be used with caution if CONV=KEEP or WAIT is also specified (see note under CONV=). |
RESTART |
|
| This parameter controls automatic restart of restores and restartable backups if a communication failure occurs and CONV=WAIT was also specified. It has 2 parameters, e.g., RESTART=3,2 (without parenthesis). The first is the number of times to attempt restart of an interrupted operation and it defaults to 0 so automatic restart is disabled by default. The second parameter is the number of minutes to wait between restart attempts and defaults to 10. When a communication error occurs and a wait to restart is begun, a message is issued to the MVS operator in case manual intervention is required to restore communications. |
TARGNAME |
|
| Specifies the FDR/UPSTREAM name of the target workstation (up to 16 characters including blanks and special characters). It allows you to identify the target workstation using a name which is independent of its current network address and connection type. TARGNAME= can be used only if the workstation is running a version of FDR/UPSTREAM which supports the FDR/UPSTREAM "Registered Name Service. |
TCPPORT | 1-65535 | 1972 | specifies the TCP/IP port for which the FDR/UPSTREAM USS Process is configured to listen for host requests This is usually set to 2972. TCPPORT= can be specified after the TCPTARG= or DNSNAME= statements. |
TCPTARG | nnn.nnn.nnn.nnn..pppp | N/a | Specifies the network address and port number of the target workstation, for those connected via TCP/IP. The network address (the IP address to which the workstation responds) is specified in “dotted decimal” form (4 decimal numbers separated by periods). The port number (the TCP/IP port on which the workstation is configured to listen for host requests, part of the FDR/UPSTREAM configuration on the workstation, usually 1972) is appended to the address as 2 more periods (or a comma) and the decimal port. For example: TCPTARG=130.50.75.5..1972 or TCPTARG=130.50.75.5,1972 |
TIMEOUT |
|
| If CONV=WAIT was specified, this specifies the number of minutes (1 to 1440) to wait for the request to complete. If it does not complete within the time limit, the request is terminated. Note that if you are issuing multiple concurrent requests from one USTBATCH, it cannot do timeout processing for more than 15 requests. |
TMAXRETRY | 0 - 9999 | 0 | Number of attempts by USTBATCH to connect to the FDR/UPSTREAM-MVS Started Task when informed that the Started Task is already at its maximum permitted task limit (MAXTASKS setting). USTBATCH will retry the operation every 10 minutes until the TMAXRETRY limit is reached or the request is accepted. |
USAPPL | 1-8 characters | UPSTREAM | specifies the VTAM APPLID of the FDR/UPSTREAM-MVS Started Task. USTBATCH uses this value to allocate an LU 6.2 conversation to the Started Task to request an operation. This value must match the value specified for APPLID parameter specified in the FDR/UPSTREAM systemwide configuration options. |
VERIFY | YES or NO | YES | YES - specifies that the names of workstation parameters present in the USTBATCH input will be verified to detect incorrect spellings. The syntax or values of those parameters are not verified. NO - requests that workstation parameter names are not verified. |
WSPARM | Valid USS filename | none | Specifies the full path name for an optional, pre-defined FDR/UPSTREAM parameter file located within the USS file system. The file name is passed to the FDR/UPSTREAM USS process to be used to obtain additional parameters that will be used to specify this operation. |
WTOCOMP | N/a | Not Specified | When specified in concert with CONV=WAIT, WTOCOMP causes USTBATCH to issue a UST747 message on the z/OS system console indicating the success or failure of each function request and a return code. This may be used for visual confirmation by the operator or for use with console automation products. |