Each of these members consist of prototype statements which openFT uses if it is creating an appropriate job internally. openFT does not check the syntax of these prototype statements. Sample members are supplied in the library SAMPLES that is delivered with openFT.
Each record contains exactly one job card (or continuation card). A maximum of 32767 records are evaluated for each member.
The following variables can be used in these prototype statements. openFT replaces these symbolic parameters with the current values:
JOBP
Job name prefix, identical to USID if the user ID does not exceed 7 characters in length. Otherwise, the last character is removed.
USID
User ID from TRANSFER-ADMISSION (for TSOVVJOB, TSOVFJOB and TSONVJOB) or from PROCESSING-ADMISSION (for JCLJOB and TSOJOB).
Maximum 8 characters, in accordance with IBM conventions.
ACCN
"accounting information" from TRANSFER-ADMISSION (PRTJOB, TSOVVJOB, TSOVFJOB and TSONVJOB) or from PROCESSING-ADMISSION (for JCLJOB and TSOJOB).
Maximum 40 characters, in accordance with IBM conventions.
PASS
Password from TRANSFER-ADMISSION (PRTJOB, TSOVVJOB, TSOVFJOB and TSONVJOB) or from PROCESSING-ADMISSION (for JCLJOB and TSOJOB). Maximum 8 characters, in accordance with IBM conventions.
OWID
Owner of the FT request, i.e. the user ID under which the transfer job was created. Maximum 8 characters according to IBM conventions.
This variable is replaced only in the system where the transfer request was issued. It is eliminated in the remote system.
PGRN
„programmer's name" as specified a subcommand in the relevant command string for follow-up processing with the keyword PGRN= (see the manual "openFT (z/OS) - Command Interface"). The PRTJOB member also assigned the value from the relevant command string for follow-up processing, i.e. from the command string in the
SUCCESS-PROCESSING on successful processing and from the command string in the FAILURE-PROCESSING if processing failed.
Maximum 20 characters in accordance with IBM conventions.
If there is no value for "programmer's name" and, after replacement of the PGRN variables inside a JOB Statement, it is established that the corresponding card has no other data except for the JCL identifier „//" and comma (separator for parameters), this card is ignored, i.e. there is no execution. This is in keeping with the recommendation in the IBM literature (JCL Reference) not to mark this missing parameter with a comma.
TRID
FT transfer ID.
Maximum 10 characters (value range 1..2147483639) in accordance with openFT conventions.
RLFN
Name of the file in which the result list is stored (PRTJOB). Maximum of 56 characters, in accordance with IBM conventions (the maximum length is obtained from the specified structure of this file name; refer to the manual "openFT (z/OS) - Command Interface" for further details).
This variable can be used in the member PRTJOB; in other members it is removed.
RLFP
Temporary file to which the preprocessing operation outputs your data (TSOVVJOB and TSOVFJOB). Maximum 38 characters in accordance with IBM conventions. This variable can only be used in the members TSOVVJOB and TSOVFJOB. In other members, it is removed.
RLFF
Temporary file to which the preprocessing operation of an ftexec command outputs its error messages. Maximum 38 characters in accordance with IBM conventions. This variable can only be used in the member TSOVFJOB. In other members, it is removed.
RLFT
Temporary file to which the preprocessing operation of an ftexec command issued in a Unix or Window partner system outputs its TSO messages. Maximum 38 characters in accordance with IBM conventions. This variable can only be used in the member TSOVFJOB. In other members, it is removed.
CONN
Name of the file containing the key for the connection to the FT subsystem. Maximum 36 characters in accordance with IBM conventions. By default, this file is created under <openft qualifier>.<inst>.CONN.This variable can only be used in the members TSOJOB, TSONVJOB, TSOVVJOB and TSOVFJOB. In other members, it is removed.
NCLO
Name of the file that contains the openFT commands. Maximum 36 characters in accordance with IBM conventions. By default, this file is created under OPENFT.NCLOAD.This variable can be used in the members TSOJOB, TSONVJOB, TSOVVJOB andTSOVFJOB. It is eliminated from other members.
PALC
Size in kilobytes of the primary allocation for the output file that is used temporarily during preprocessing with the FTEXEC command.
Default value: 256
If you want to change this value then you must modify the value for DEFFSIZE in the PARM file (see section “Structure of the PARM member”). Modifying the value of DEFFSIZE not only affects the size of the temporary file during preprocessing with FTEXEC but also more generally affects the temporary files used during preprocessing for interim data output.
Example: If you double the default value for DEFFSIZE (2621440) then the value 256 is doubled.
SALC
Size in kilobytes of the secondary allocation for the output file that is used temporarily during preprocessing with the FTEXEC command.
Default value: 2560
If you want to change this value then you must modify the value for DEFFSIZE in the PARM file (see section “Structure of the PARM member”). Modifying the value of DEFFSIZE not only affects the size of the temporary file during preprocessing with FTEXEC but also more generally affects the temporary files used during preprocessing for interim data output.
Example: If you double the default value for DEFFSIZE (2621440) then the value 2560 is doubled.
The names of these variables should have as many trailing "#" fill characters as are necessary for a field to be set to its maximum length (including the "&" character, e.g. &TRID#####). When replacing the variables by the current values, openFT does not exceed the field length predefined by the name of the symbolic parameter including the trailing "#" fill characters; if necessary the current values are truncated. On the other hand, where the current values are shorter than this field length, openFT removes superfluous fill characters.
Note
If a follow-up processing job of the type ALLOC DSNAME (...) was specified, openFT also replaces the variables in this job before passing it to the Internal Reader.
When creating sample instructions, the requirements of the relevant z/OS installation for executable jobs must be observed. As a rule, the JOB statement requires a valid user ID, valid accounting information and a valid user password. These values can be taken from the following sources:
They are specified by the user in the NCOPY command (for PRTJOB, TSOVVJOB, TSOVFJOB and TSONVJOB in the TRANSFER-ADMISSION, for JCLJOB and TSOJOB in the PROCESSING-ADMISSION).
If FTAC is used, the specifications for PROCESSING-ADMISSION can also be defined within an admission profile. The admission to perform preprocessing and postprocessing is defined via the specifications for the TRANSFER-ADMISSION.
They are contained in the JOB statements in the PRTJOB, JCLJOB,TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB members, i.e. no variables are used for the user ID, accounting information and user password. In this case, the specifications apply for all jobs.
These notes also apply to default jobs created by openFT if the TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB members do not exist.
The examples below reflect the default structure of the jobs created by openFT. Deviations specific to the computer center can be implemented in the members PRTJOB, JCLJOB, TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB.
Example of the member PRTJOB
//&JOBP##P JOB &ACCN#########################,
// &PGRN################,
// MSGCLASS=X,
// CLASS=C,
// USER=&USID###,PASSWORD=&PASS###
//PRTJOB EXEC PGM=IEBPTPCH
//SYSPRINT DD DUMMY
//SYSUT1 DD DSN=&RLFN#########################################,
// DISP=(SHR,DELETE),
// DCB=(RECFM=FB,LRECL=134,BLKSIZE=2546)
//SYSUT2 DD SYSOUT=A,DCB=(LRECL=134)
//SYSIN DD *
PRINT PREFORM=A
/*
//
In this example the user ID, account number and password are inserted by openFT from the user's TRANSFER-ADMISSION entry. For the PGRN variable, the value specified by the user with the keyword PGRN= as subcommand in the command string for follow-up processing is used (for more detail, please refer to the manual "openFT (z/OS) - Command Interface"). If no value exists for „programmer's name", this card is ignored, i.e. there is no execution, since it contains no other data except for the JCL identifier „//" and comma (separator for parameters). If job processing is successful, the value is taken from the command string in the SUCCESS-PROCESSING parameter; if not, it is taken from the command string in the FAILURE-PROCESSING parameter. If no value exists for „programmer's name", this card is ignored, i.e. there is no execution, since it contains no other data except for the JCL identifier „//" and comma (separator for parameters). In addition, the name of the file with the result list is inserted (the field &RFLN##...## provided for this name should be 32 characters long). openFT then initiates this job.
Example of the member JCLJOB
//&JOBP##N JOB &ACCN#######################, // MSGCLASS=X, // CLASS=C, // REGION=2M, // USER=&USID###, // PASSWORD=&PASS### //JOBLIB DD DSN=&USID###.PROCLIB,DISP=SHR
In this example the user ID, the account number and the password are inserted by openFT from the user's PROCESSING-ADMISSION entry. For the PGRN variable, the value specified by the user with the keyword PGRN= as subcommand in the command string for follow-up processing is used (for more detail, please refer to the manual "openFT (z/OS) -
Command Interface"). If no value exists for „programmer's name", this card is ignored, i.e. there is no execution, since it contains no other data except for the JCL identifier „//" and comma (separator for parameters).
The JCL statements specified by the user in the NCOPY command as follow-up processing are added by openFT after the prototype statement "//JOBLIB DD ...". openFT then initiates this job.
Example of the member TSOJOB
//&JOBP##N JOB &ACCN###################################, // &PGRN###############, // MSGCLASS=X, // CLASS=C, // NOTIFY=&USID###, // USER=&USID###, // PASSWORD=&PASS###, // REGION=0M // EXEC PGM=IKJEFT01 //OPENFT DD DSN=&CONN#########################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#########################################, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD *
In this example the user ID, the account number and the password are inserted by openFT from the user's PROCESSING-ADMISSION entry. For the PGRN variable, the value specified by the user with the keyword PGRN= as subcommand in the command string for follow-up processing is used (for more detail, please refer to the manual "openFT (z/OS) - Command Interface"). If no value exists for „programmer's name", this card is ignored, i.e. there is no execution, since it contains no other data except for the JCL identifier „//" and comma (separator for parameters). The TSO commands specified by the user in the
NCOPY command as follow-up processing, as well as the end of data terminator "/*", are added by openFT after the prototype statement "//SYSTSIN DD *". openFT then initiates this job.
Example of the member TSOVVJOB
//&JOBP##N JOB &ACCN###################################, // MSGCLASS=X, // CLASS=C,MSGLEVEL=(1,1), // USER=&USID###, // PASSWORD=&PASS###, // REGION=0M //STEP0 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#########################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#########################################, // DISP=(SHR,KEEP) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSTSIN DD * FTATTP &PRID
In this example, the user ID, account number and password are inserted by openFT from the user’s TRANSFER-ADMISSION. openFT allocates the appropriate files for the variables CONN, NCLO and RLFP.
If %TEMPFILE was not specified during preprocessing, openFT extends the job as follows:
//******************************************************** //STEP1 EXEC PGM=IEFBR14 //STDOUT DD DSN=&RLFP#################################, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PS,BLKSIZE=1536,RECFM=VB), // UNIT=SYSDA,SPACE=(1,(256,2560)),AVGREC=K //******************************************************** //IFBAD IF STEP0.RC=0 THEN //STEP2 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD DSN=*.STEP1.STDOUT,DISP=(MOD,KEEP,DELETE) //SYSTSIN DD * //IFBADEND ENDIF
If %TEMPFILE was specified during preprocessing, openFT extends the job as follows:
//IFBAD IF STEP0.RC=0 THEN //STEP2 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSTSIN DD * //IFBADEND ENDIF
Example of preprocessing using %TEMPFILE on a Windows or Unix system:
ncopy zospartner!"|ftscopy from,WindowsPC,(%tempfile),*any('hallo.txt'\
,trans='WindowTransadm')" - zosTransadm
openFT inserts the TSO or openFT commands specified as preprocessing in the FT request as instream data cards after the template statement "//SYSTSIN DD *". The TSO commands must comply with the IBM conventions. They can be of any length and, if necessary, openFT will spread the command over multiple lines. Any output from the openFT commands as part of preprocessing is redirected to SYSPRINT and consequently to the file referenced by RLFP. By default, TSO commands output to SYSTSPRT. It may be necessary to redirect this output to SYSPRINT and thus to the output file for preprocessing (e.g. LISTCAT OFILE(SYSPRINT)). When the preprocessing commands have been read in, openFT passes the subsequent commands to the internal reader for batch processing (this part is generated dynamically and cannot be modified).
//******************************************************** //IFBAD IF (ABEND OR STEP2.RC>=12 OR NOT STEP2.RUN) // THEN //STEP3 EXEC PGM=IKJEFT01 //OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP) //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * FTDETP FAILURE &PRID // ELSE //STEP4 EXEC PGM=IKJEFT01 //OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP)
//SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * FTDETP SUCCESSFUL &PRID //IFBADEND ENDIF /*
openFT then starts this job. If processing is aborted, openFT starts its own "Cancel-Job" on the basis of the job envelope TSOJOB. This job is assigned the letter "Z" as the last letter of the job name to give it a higher priority than the current processing jobs.
Example of the member TSOVFJOB
//&JOBP##N JOB &ACCN###################################, // MSGCLASS=X, // USER=&USID###, // NOTIFY=&USID###, // PASSWORD=&PASS###, // REGION=0M //STEP0 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSTSIN DD * FTATTP &PRID //******************************************************** //STEP1 EXEC PGM=IEFBR14 //STDOUT DD DSN=&RLFP#################################, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PS,BLKSIZE=1536,RECFM=VB), // UNIT=SYSDA,SPACE=(1,(&PALC######,&SALC######)), // AVGREC=K //STDERR DD DSN=&RLFT#################################, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PS,BLKSIZE=1536,RECFM=VB,LRECL=1532), // UNIT=SYSDA,SPACE=(1,(256,2560)),AVGREC=K //SYSERR DD DSN=&RLFF#################################, // DISP=(NEW,CATLG,DELETE), // DCB=(DSORG=PS,BLKSIZE=1536,RECFM=VB,LRECL=1532), // UNIT=SYSDA,SPACE=(1,(256,2560)),AVGREC=K //******************************************************** //IFBAD IF STEP0.RC=0 THEN //STEP2 EXEC PGM=IKJEFT01, // COND=(0,NE)
//OPENFT DD DSN=&CONN#################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#################################, // DISP=(SHR,KEEP) //SYSPRINT DD DSN=*.STEP1.STDOUT,DISP=(MOD,KEEP,DELETE) //SYSTSPRT DD DSN=*.STEP1.STDERR,DISP=(MOD,KEEP,DELETE) //SYSERR DD DSN=*.STEP1.SYSERR,DISP=(MOD,KEEP,DELETE) //SYSTSIN DD *
A special form of preprocessing in z/OS takes the form of the server function for an "ftexec" command issued in partner system. ftexec expects to be returned the output from the passed commands (stdout), any error messages that occur (stderr) and an exit code.
openFT inserts the TSO or openFT commands specified as preprocessing in ftexec as instream data cards after the template statement "//SYSTSIN DD *". The TSO commands must comply with the IBM conventions. They can be of any length and, if necessary, openFT will spread the command over multiple lines. openFT dynamically appends the output from SYSTSPRT to that of SYSERR. To do this, it internally uses the IBM utility IEBGENER:
//IFBADEND ENDIF //STEP22 EXEC PGM=IEBGENER //SYSUT1 DD DSN=*.STEP2.SYSTSPRT,DISP=(MOD,DELETE,DELETE) //SYSUT2 DD DSN=*.STEP2.SYSERR,DISP=(MOD,KEEP,DELETE) //SYSIN DD DUMMY //SYSPRINT DD SYSOUT=* //SYSTSIN DD *
The content of the temporary file generated by this is redirected to "stderr" in the partner system and SYSPRINT is redirected to "stdout". After reading in the commands, openFT extends the job in accordance with the example for TSOVVJOB, see job steps STEP 3 and STEP 4 in section “Structure of the members PRTJOB, JCLJOB, TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB”.
Example for the member TSONVJOB
//&JOBP##N JOB &ACCN###################################, // MSGCLASS=X, // CLASS=C,MSGLEVEL=(1,1), // USER=&USID###, // PASSWORD=&PASS###, // REGION=0M //STEP1 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#########################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#########################################, // DISP=(SHR,KEEP) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSTSIN DD * FTATTP &PRID //******************************************************** //IFBAD IF STEP1.RC=0 THEN //STEP2 EXEC PGM=IKJEFT01, // COND=(0,NE) //OPENFT DD DSN=&CONN#########################################, // DISP=(SHR,KEEP) //STEPLIB DD DSN=&NCLO#########################################, // DISP=(SHR,KEEP)
In the case of postprocessing in z/OS, the transferred data is first stored in a temporary file which is then available as input for the commands specified in the request (TSO commands or system commands for corresponding utilities). The temporary file can be directly referenced in the commands by means of the metastring %TEMPFILE.
openFT then extends the job as follows:
//SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD * //SYSTSIN DD * //IFBADEND ENDIF
If %TEMPFILE is not used in the postprocessing commands, then postprocessing reads in the data via SYSUT1. The data stream from the FT request read via SYSTSIN then uses the data specified in SYSUT1 as input data. To this end, users can specify a corresponding utility program in the postprocessing operation in order to access this data.
openFT then extends the job as follows:
//SYSUT1 D DSN=&RLFP##########################################, // DISP=(MOD,KEEP,DELETE) //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSIN DD * //SYSTSIN DD * //IFBADEND ENDIF
Example
The user wants to copy a file DAT1 from a Windows or Unix system to z/OS using ncopy. Via the postprocessing operation, the file DAT1 is to copy to another file DAT2 in the target system. The utility IEBGENER is used:
ncopy DAT1 ZosPartner!”|allocate dsname(DAT2) ddname(SYSUT2) mod keep dsorg(ps) recfm(v,b) lrecl(259); ‘call SYS1.LINLLIB(IEBGENER)’” UserId,Account,Password
In all cases, the postprocessing job is extended by further statements after the processing commands in the same way as preprocessing jobs. This is performed in the same way as for the preprocessing job (see TSOVVJOB in section “Structure of the members PRTJOB, JCLJOB, TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB”).
If processing is aborted, openFT starts its own "Cancel-Job" on the basis of the job envelope TSOJOB. This job is assigned the letter "Z" as the last letter of the job name to give it a higher priority than the current processing jobs, see TSOVVJOB with the job steps STEP 3 and STEP 4 in section “Structure of the members PRTJOB, JCLJOB, TSOJOB, TSOVVJOB, TSOVFJOB and TSONVJOB”.