JCL and parameters for ACQPUSH using UCOPY - syncsort_capacity_management - 12 - 12.40

Parameters for ACQPUSH

ACQPUSH reads the //PARMDATA file for instructions on how to proceed. For the most part, parameters are case-insensitive so, for example, QUIT=Y or quit=y or Quit=Y are all treated the same.

The options available are:

GATEKEEPER=N| | Y

Gatekeeping forces Control Center to check that data is all contiguous before applying it to its database. Set this parameter to Y to name an output file with a prefix of the letter 'g' for gatekeeping to be performed.

KEEPDARK=N | Y

When pushing a file with FTP and not creating a '.ready' directory, it is copied with the first character set to a 'p' to avoid it being detected by Control Center, and a '2' replaces the 'p' when the copy is complete. Set KEEPDARK=Y to not perform this file rename, keep it prefixed with a 'p', and therefore invisible to Control Center. You may want to use this if you have multiple hops across which to transport files before finally where they will be processed by Control Center. In this case the final file rename is something you will have to perform yourself.

MAKEREADY=Y | N

Create and navigate to a directory named tgt<nnnnnnnn>.ready before other commands, or not. This form of directory name is what Control Center creates when it collects data, and used carefully, can avoid the need for additional copying of files.

MULTI=Y | N

Create a MULTIZOS file from the input data, or not. If MULTI=N is set and data from multiple systems is present in the file the output name will be altered from <datetime>_aszs<TTTTTTTT>.nnnn to <datetime>_aszsMULTIZOS.nnnn unless GATEKEEPER=Y or ALLOWMULTI=N is in effect.

PUSHWITH=FTP | UCOPY

ACQPUSH will generate FTP commands to copy data by default. The alternative is the 'ucopy' command, part of the Stonebranch Inc 'Universal Command' product.

If you select UCOPY then MULTI=N and ALLOWMULTI=N will be forced and QUIT= and USEDSN= wll be ignored if provided.

PUT=PUT | SPUT

This parameter controls the generation of the command used to copy data. The default is PUT and is used for the standard 'put' command. The alternative is SPUT which will generate a 'sput' command, it is used by the commercial Tectia SSH z/OS client.

QUIT=Y | N

Generate an FTP 'quit' command at the end of the command strea, or not.

USEDSN=Y | N

If set to Y (the default) then ACQPUSH will write 'put' and 'rename' FTP commands with using the z/OS dataset name. If set to N then ACQPUSH will write 'put' and 'rename' FTP commands using the DDNAME for the incoming file. The purpose of this is to allow data on a tape drive to be RETAINED in JCL to avoid it being dismounted.

Unless you are using Syncsort Capacity Management Gatekeeping it will generally cause no problems to ACQPUSH or Control Center if a MULTIZOS file is written but the data only contains one target and ACQPUSH will force the use of MULTIZOS if it detects that there is data from more than one system in the input file, or if disk occupancy data is present. A warning message will be written to show this has happened.

If you plan to use Syncsort Capacity Management Gatekeeping, there is an explicit requirement for the data to only belong to a single system and switching to MULTIZOS is not allowed.

Parameters for use with the SPLIT facility

SPLIT processing will read the //ATHDATA file and dynamically allocate datasets into which are written complete, smaller, sections of data ready for Control Center to process.

The commands to generate the copying of data are written to //CMDFILE. Please note in previous versions of ACQPUSH this file name was //PUSHFTP and you must change your JCL to use the new file name from v12.40 onwards.

The commands for IDCAMS to delete these split files are written if SPLITDEL=Y is in effect and a //DELFILE DD is present in JCL.

Both files have attributes of LRECL=80 and RECFM=FB.

The commands you wish to use are provided as parameters after CMDS=BEFORE, CMDS=BODY and CMDS=AFTER parameters.  The commands after CMDS=BODY can contain the following editable strings:

!Z! - the dynamically allocated z/OS dataset name

!W! - the name of the file as it needs to be in Windows for Control Center to process it

!T! - the target number of the data in the z/OS dataset

You can use the strings !z| or !Z!, !w! or !W! and !t! or !T! - this part is case insensitive. All the rest of the command statements are handled exactly as provided.

These editable strings can appear multiple times and across multiple statements. As an example, this mimics what the classic use of ACQPUSH does, in these two statements:

CMDS=BODY
put '!z!' p!w!
rename p!w! !w!

This would generate FTP statements for each file to put the dynamically allocated z/OS dataset name containing a segment of data to a Windows file name with a 'p' on the front so Control Center did not "see" it before it was all copied, then generate a rename to take the 'p' prefix off so it could be found for processing.

Within the limits of an 80-character record you can enter whatever statements you wish in order to effect your data transfer, for example this might work for Connect:Direct:

CMDS=BODY
STEP1 COPY FROM (DSN='!Z!') -
           TO (DSN='!W!' - 
           SYSOPTS="DATATYPE(TEXT)" -
           DISP=(RPL)

Commands included with the optional CMDS=BEFORE or CMDS=AFTER are written to //CMDFILE exactly as provided - no substitution of dataset names, files names or target numbers is performed.

If you use the SPLIT facility, then only the parameters listed in this section are used to direct processing and any other parameters are ignored if you provide them, apart from the CHECKLAST= parameter, which is honored.

You scan process a dataset with the SPLIT facility that contains data from multiple targets - the MULTIZOS feature does not apply here as each new target or type of data (system, DASD) detected will generate a new name using tokens for the tar­get number and date.

SPLIT= N | Y

When SPLIT=Y is set it tells ACQPUSH to use the SPLIT facility

SPLITPFX=name

This parameter sets the z/OS dataset prefix for split files. There is no default and it must be provided. It can be from 1 to a maximum of 30 characters in length as the suffix generated for each is 14 characters long.  The dataset name that will be generated is of the form:

<SPLITPFX>.<x><tt><dd>.T<hhmmss>

<SPLITPFX> is the value of the SPLITPFX= parameter

<x> is 'S' for system data and 'D' for DASD occupancy data from Acquire/DASD

<tt> is a token for the 8-digit target number, from '00' to 'FF'

<dd> is a token for the first interval start date in this dataset, from '00' to 'FF'

<hhmmss> is the first interval start time in this dataset

Do not end the SPLITPFX= parameter with a period (.) - this is automatically added in the suffix that is generated for each dataset.  There is no validation of the SPLITPFX= parameter, so you must ensure it is acceptable for your environment and complies with JCL requirements.

SPLITUNIT=SYSALLDA | unitname

This parameter sets the allocation unit for datasets. The default is SYSALLDA.

SPLITSIZE=100 | n

This parameter sets the approximate size of the generated datasets in - the default is 100 MB. The value you specify here is converted to cylinders and used for the primary allocation, and the value is divided by 10 for the secondary allocation.

The size is approximate as the data is always split at the point where a trailer record (type 9999) is processed. All allocations have the equivalent of the JCL RLSE parameter set to free up space that is not needed.

SPLITCLEAN=N | Y

This parameter allows you to choose to make sure there that no datasets with the names likely to be allocated by this run are in existence before continuing. The default is not to do this, as you may have set SPLITDEL=Y in previous run and used the IDCAMS commands so generated to tidy up any datasets.

CMDS=BEFORE

This parameter indicates that what follows from here are commands to write once, to the beginning of the //CMDFILE, before processing data from //ATHDATA. Multiple entries may follow (up to 100 items).

CMDS=BODY

This parameter indicates that what follows from here are editable commands to have variables replaced before being written to the //CMDFILE file for onward use by a data mover utility. Multiple entries may follow (up to 100 items) containing !Z! !W! or !T! strings.

CMDS=AFTER

This parameter indicates that what follows from here are commands to write once, to the //CMDFILE after all processing of data from //ATHDATA is complete.  Multiple entries may follow (up to 100 items).

CMDS=END

This parameter signifies that additional ACQPUSH parameters may follow. This parameter is optional if the commands being provided end with the end-of-file. It is only required if you wish to add further SPLIT parameters after your commands.

You can omit any of the BEFORE, AFTER and END items but you must provide at least one command in the CMDS=BODY section, and there must be at least one editable string.

Examples of commands generated by ACQPUSH

The following examples show the various commands generated by combinations of parameters to ACQPUSH. Assume the following:

• Dataset CP.ZOS.DATA contains data created by Acquire for systems MRT4 and PRD7

• System MRT4 was assigned target number 10037 in the Acquire parameters

• The first interval in the file started at 09:00:00 on 02MAY16

With parameters of:

MULTI=Y
MAKEREADY=Y
QUIT=Y

the following FTP commands will be generated:

mkdir tgt00010037.push
cd tgt00010037.push
put 'CP.ZOS.DATA' +
20160502090000_aszsMULTIZOS.1110
cd ..
rename tgt00010037.push tgt00010037.ready
quit

Note that these commands create a directory with a suffix of .push, copies the data then renames the directory to .ready. This ensures data has been copied in full before making it available to Control Center.

Parameters of:

MULTI=N
MAKEREADY=N
QUIT=Y

will see the following FTP commands generated:

put 'CP.ZOS.DATA' +
p01670502090000_aszsMULTIZOS.1110
rename p0160502090000_aszsMULTIZOS.1110 20160502090000_aszsMULTIZOS.1110
quit

Note in this instance no directory is created and it is assumed the user will set a directory location in the commands provided to FTP prior to concatenating the ones generated here. Again, the file is copied to a temporary name and renamed to fit Control Center’s requirements afterwards. Also note that because a second system was detected in the data the output file is now called MULTIZOS, and Control Center will split out the data by target number and process it appropriately.

In one-step mode all the commands generated by ACQPUSH replace the !push string in the //ACQFTP file.