Compressed Dataset Access Method (CDAM)

This chapter contains the following topics:

• Overview

• How to Use CDAM

  • Activating the CDAM

  • CDAM Parameters

  • Parameter DSN of the DD Statement

• CDAM Logic

• CDAM Dataset Naming Conventions

  • Multijob CDAM Datasets

• CDAM User Exit CTDX018

• CDAM Maintenance Utility CTDAMUTI

  • Activating the Utility

  • Parameter Format

• Migrated CDAM Datasets

• IOA Archive Server

  • Media and Resource Management

  • OSS Media

  • FTK Media

  • CART Media

• CDAM Encryption

  • Control-D CDAM Encryption Activation

  • User Exit CTDX029

Overview

This chapter should be read very carefully. It deals with performance considerations for managing large volumes of SYSOUTs. Although Control-V can be implemented effectively using the conventional "job writes reports to spool" method, it is possible to improve the efficiency of the data center by writing reports directly to compressed datasets.

Control-V can use two report processing techniques. The basic technique does not require any JCL changes and can be implemented immediately on any given report. The following diagram shows the basic report processing workflow:

Figure 455 Control-V Basic Report Processing Workflow

The basic workflow is:

• Jobs write reports to the JES spool.

• Control-D monitor reads the reports from the spool.

• Control-D monitor writes the reports to compressed datasets while deleting the original copy from the JES spool.

• The decollating process is carried out while the reports are moved from the spool to the compressed datasets.

This type of process is reliable and is used by many report management systems. However, it is not the best solution in terms of overall system performance. The inherent problems of this method are:

• Redundant write operations. The same report is written to the spool, then it is read from the spool and (again) written to compressed datasets. The writing of the report to the spool is redundant because the report finally resides on compressed datasets.

• Use of the JES spool. This method is inefficient because:

  • The JES spool is a large pre-allocated DASD space. It must be large enough to contain many of the largest reports. Since it is a pre-allocated area, that area cannot be used for other purposes (for example, sort work areas) even when spool utilization is low.

  • The data on the spool is not compressed and is not structured efficiently. This results in a waste of space. A significant portion of the spool is full of blanks.

  • A sysout on the spool can be deleted (purged) very easily by indirect commands (for example, an operator may delete the entire sysout output class). Therefore, reports can disappear from the spool before they are printed and a rerun of the job is required to recreate the report.

  • Most security products have serious problems protecting data on the spool. Consequently, the spool is a potential security leak and sysouts on spool are not protected using conventional security methods.

  • Although 100% spool utilization must be avoided at all costs, this situation can occur very easily when many reports and dumps are written to the spool.

  • The JES spool is one of the most highly used components of the operating system. Programmers access the spool frequently to scan the JES queues using SDSF, FLASHER, ISPF, and TSO OUTPUT commands. The overhead for this activity depends on the number for outputs on the spool. If the spool contains unnecessary data, system overhead is unnecessarily increased.

The Compressed Dataset Access Method (CDAM) solves all of these problems. It also has other benefits:

• Reports are written directly to compressed sysout. They do not pass through the spool, thereby avoiding redundant write operations.

• The elapsed time of jobs which create large reports is reduced by 10% or more.

• Since CDAM sysouts are written to specified units, there is no need for pre-allocated space. The CDAM allocates space only when it is actually needed and unused space is released for general use at the end of the job. There is no danger of a SB37 abend (space shortage) unless the specified unit is completely full. It is possible to define the entire free area in all the disks in the data center as one large potential "spool" for CDAM.

• The CDAM performs report compression. The compression rate is 30% to 70% depending on the type of data.

  A report stored in a compressed dataset is subject to all the security rules of the installation since it is a regular sequential dataset. Multi-user access to a compressed report is available only via the Control-V Online interface, and only to authorized users using regular dataset protection. The compression routine also acts as an encryption mechanism.

• The danger of 100% spool utilization is greatly reduced because large reports and dumps (for example, from CICS) are no longer written to the spool.

• Using CDAM, the number of sysouts on the spool is reduced; therefore, the overhead related to spool operations is reduced.

The following diagram shows the report workflow using the Compressed Dataset Access Method:

Figure 456 Control-V Report Workflow Using the Compressed Dataset Access Method

The recommended report processing workflow is:

• Jobs write reports to compressed datasets.

• Control-D monitor reads the reports from the compressed datasets and decollates them.

The Control-D monitor uses compressed reports in both workflows. The means by which Control-V (or the user) can create and read compressed reports is called the Compressed Dataset Access Method (CDAM).

CDAM is a general access method by which sysouts (reports) can be written to compressed datasets. To invoke CDAM, the user must modify the JCL of the job so that the reports are written to compressed datasets and not to the spool. There is no need to change the application program which produces the reports.

The following paragraphs describe CDAM in detail.

How to Use CDAM

The Compressed Dataset Access Method (CDAM) can be activated on any DD statement in the job which writes a sequential output file to spool.

//J01VV    JOB    ....
//STEP01   EXEC   PGM=XXXXXX
//PRINT    DD     SYSOUT=A

//J01VV    JOB    ....
//STEP01   EXEC   PGM=XXXXXX
//PRINT    DD     SUBSYS=(CDAM,'SYSOUT=A,PREFIX=J01')

Activating the CDAM

Use the following syntax to activate CDAM:

//ddname DD SUBSYS=(subsys-name,'parameters')

where

• ddname is any standard DDname can be used

• subsys-name is the name assigned to the Compressed Dataset Access Method at installation time. The name can be site dependent and is defined by Control-V installation parameter AMNAME. Throughout this guide the name CDAM is used.

• parameters are CDAM parameters (described below)

The SUBSYS parameter is a standard JCL parameter. For detailed information about this parameter, refer to the relevant operating system publications.

Compressed Dataset Access Method parameters can span more than one line. In this case, the following JCL syntax should be used:

//PRINT    DD  SUBSYS=(CDAM,'PREFIX=J08,UNIT=PROD',
//         'OUTLIM=30000')

CDAM Parameters

Compressed Dataset Access Method parameters are divided into the following categories:

• Sysout control parameters

• Access method control parameters

Sysout Control Parameters

JCL syntax rules forbid the use of certain DD subparameters when the SUBSYS option is used. For example, the following JCL statement results in a JCL syntax error:

//PRINT DD SUBSYS=(CDAM,'XXX'),OUTLIM=100000

To overcome this problem, the user can pass the following sysout control parameters directly to the CDAM:

• BURST

• CHARS

• COPIES

• DEST

  DEST can only contain a node; it cannot contain a user ID.

• FCB

• FLASH

• FORMS

• MODIFY

• OPTCD

• OUTLIM

• OUTPUT

• SYSOUT

• TRC

• UCS

• PAGEDEF

• FORMDEF

The syntax of the parameters is identical to the JCL syntax as described in the relevant operating system publications. CDAM checks for the correct syntax

//PRINT DD SUBSYS=(CDAM,'OUTLIM=100000,SYSOUT=(class,extwtr,form)')

The following sysout control parameters do not behave like standard JCL statements:
OUTPUT=name

This parameter designates the name (1 through 8 characters) of a JCL OUTPUT statement in the Printers Control monitor. It can be specified in the PRINT/CDAM PARMS field of a report decollating mission usually used for decollating AFP output. This OUTPUT statement must be defined in the JCL of the Printers Control monitor. It usually contains the parameters FORMDEF and PAGEDEF (used for AFP output). Control-V does not check whether or not the OUTPUT statement exists in the Printers Control monitor. It is the user’s responsibility to provide a valid OUTPUT statement name.

PAGEDEF=name

This parameter designates the name (1 through 6 characters) of a page definition to be used for printing the output. The page definitions must reside in PAGEDEF libraries specified to Control-V. For information about specifying libraries, refer to the Control-D chapter of the INCONTROL for z/OS Installation Guide.

Do not specify the PAGEDEF parameter together with the OUTPUT parameter. If you do so, the OUTPUT parameter overrides the PAGEDEF parameter.

FORMDEF=name

This parameter designates the name (1 – 6 characters) of a form definition to be used for printing the output. The FORMDEF parameter must reside in a FORMDEF libraries specified to Control-V. For information about specifying the libraries, refer to the Control\--D chapter of the INCONTROL for z/OS Installation Guide.

Do not specify the FORMDEF parameter with the OUTPUT parameter. If you do so, the OUTPUT parameter overrides the FORMDEF parameter.

COPIES=nn

The sysout control parameter COPIES can be used to specify the number of copies to print if both the JOB DEFAULTS COPIES parameter and the JOB DEFAULTS MAX COPIES parameter of the report decollating mission are both set to 99.

TRC=

Setting parameter TRC (Table Reference Character) to YES produces the same result as including the expression OPTCD=J in the JCL.

CDAM Control Parameters

The following parameters are used to control the functions performed by the CDAM:

ACIF={YES | NO | ONLY | ALL}

The ACIF parameter settings determine the conversion format and destination of the printing mission, as outlined in Table 277.

Table 277 ACIF Parameter Settings

If the report has ACIF indexes, the original ACIF indexes remain available. However, identical Control-V indexes are created when the printing mission is processed. The new Control-V indexes enable the user to access a specific index value through Control-D/Page On Demand.

For more information about ACIF and Control-D/Page On Demand, see the Control-D and Control-V chapter of the INCONTROL for z/OS Administrator Guide.

For more information about the STORE parameter, see STORE: Mission-Specific Parameter.

ALLOCOPT={ONEDSN | JOBSDSN1 | JOBSDSN2}

The ALLOCOPT parameter can be specified in the PRINT/CDAM PARMS field of any ON statement except ON DSN. If specified elsewhere (during a write operation), an error message is not produced and the parameter is ignored.

When Control-D decollates a report from spool, it creates the following entities:

• A CDAM file containing the compressed report. A CDAM file is created for every JES dataset (usually corresponding to every job DDstatement).

• A report descriptor entry in the Active User Report list ($SYSDATA record). This record contains general information about the compressed CDAM file and pointers to the beginning and end of the report.

• One or more user or report entries in the Active User Report list. This record contains the report name and pointers to the beginning and end of the report pages belonging to the user.

Under "classical" circumstances, such as a large sysout distributed to many users, the decollation results are:

• One CDAM dataset.

• One SYSDATA entry describing the CDAM dataset.

• Many user and report entries describing each recipient of (any part of) the report.

However, Control-V is not only used for distributing reports to users. Another common usage of Control-V is to archive MSGCLASS output from production jobs. Following is a schematic example of a report decollating mission definition used for this purpose:

ON CLASS A
  WHEN - no data in the WHEN statement
     DO USER         PRODCNTL
     DO NAME         PRODUCTION MSGCLASS
     DO BACKUP       BCK0031D

If special CDAM allocation options are not used, the decollation results are:

• Many CDAM files (three JES job datasets; one file for each DD statement).

• Many SYSDATA entries (one for each CDAM dataset).

• One user or report entry describing all the CDAM datasets.

This technique increases the number of records in the Control-V user files, resulting in inefficient resource usage. It wastes space and slows down Control-V operation. Space utilization on the disk is not efficient because each small CDAM dataset occupies one whole track.

The following ALLOCOPT (allocation) options can be used to remedy these problems:

ALLOCOPT=ONEDSN

When the above decollation is activated with this option, the results are:

• One CDAM dataset containing all sysouts of the job (from the decollated class).

• One SYSDATA entry for the entire CDAM dataset.

• One user or report entry.

Under this option, Control-V assumes that the printing parameters of the first decollated JES dataset apply to all SYSOUTs in the CDAM dataset. Translation from machine printing control characters to ASA control characters is accomplished automatically at printing time.

ALLOCOPT=JOBSDSN1

When the above decollation is activated with this option, the results are:

• The sysouts are written to a multi-job CDAM dataset (see below).

• One SYSDATA entry for each job, describing all the sysout datasets of this job.

• One user or report entry.

Under this option, Control-V assumes that the printing parameters of the first decollated JES dataset of the job apply to all SYSOUTs of the job. Translation from machine printing control characters to ASA control characters and vice versa is accomplished automatically at printing time.

ALLOCOPT=JOBSDSN2

When the above decollation is activated with this option, the results are:

• The sysouts are written to a multi-job CDAM dataset (see below).

• One SYSDATA entry for each JES sysout dataset (as in "classical" decollation).

• One user or report entry.

Under this option, the printing parameters of each dataset are kept automatically.

APA=YES or NO

The APA parameter can be set to YES for AFPDS reports or to NO for regular reports. The default value is YES if the report contains only AFP lines (which begin with hexadecimal 5A). Otherwise, the default value is NO. The parameter is optional.

For an explanation of how setting the APA parameter to YES affects report indexes, see .

ASSOC=associationtype

This parameter specifies the report file type (for example, DOC, PDF, AFP).

Reports viewed using Control-D/Page On Demand or CTDWA are viewed according to the specified ASSOC value. For example, a report with association type PDF is viewed with Adobe Acrobat.

BLOB=imagetype

The presence of this parameter indicates that the report was created with Control-D/Image. The value indicated by BLOB is the image type specified when implementing Control-D/Image (for example, DOC, GIF, JPG).

For more information about Control-D/Image, see the Control-D and Control-V chapter of the INCONTROL for z/OS Administrator Guide.

BLOCKS=number

This parameter specifies the number of blocks allocated for the first "logical" extent of the compressed dataset. The parameter is optional. The default is defined by the Control-D installation parameter AMBLK#D.

The parameter should be used when the user wants to control the allocation algorithm of CDAM in order to improve system performance. For a full explanation, see CDAM Logic.

//PRINT DD SUBSYS=(CDAM,'BLOCKS=280')

CMPEXT=YES

This parameter can be used as a CDAM parameter in PRINT/CDAM PARMS in decollation mission definitions, and as a SUBSYS parameter in JCL.cards.

When this parameter is used, Control-D saves in the Control-D repository most of the printing parameters that are used in the OUTPUT card when the SYSOUT is created in the spool. These parameters can later be used automatically during Control-D printing. In this case, optional wish WD3133 (Dynamic allocation of OUTPUT card) must be activated with DATAC=ALL or DATAC=CMPEXT:

ID=WD3133,APPLY=YES,DATA=0,DATAC=ALL

CMPRTN=name

The name of the compression and decompression routine. This parameter overrides the default compression routine supplied with Control-V. The current default routine has a compression rate of 30% – 70% for reports and dumps.

DATE=jjj

The day in the year in Julian format. This parameter represents the day on which the compressed SYSOUT was created. This parameter can be used for retrieval purposes. If a different date is desired when creating a CDAM file, use the DSN field of the DD statement, which is described in Parameter DSN of the DD Statement.

DDNAME=name

This parameter can be used for retrieval. The format is a 1 - 8 character, valid DD name. This parameter represents the DD name from which the compressed sysout has been created.

DEBUG={YES|NO|debug levels}

This parameter helps Control-V support personnel solve problems. The parameter is optional. The default setting of DEBUG is NO (that is, no special debug printout). When DEBUG is set to YES, or debug levels are specified, CDAM writes special messages, snaps and other relevant data to DD statement CDAMSNAP. Debug levels are specified by a sequence of 1-8 digits, where each digit specifies a debug level. CDAM expects this DD statement to be defined in the job step. This DD statement must not use CDAM. The debugging messages must be directed to the spool or to a regular sequential dataset. In the following example, debug levels 1, 4, and 5 are set for the CDAM file:

//PRINT    DD     SUBSYS=(CDAM,'PREFIX=J01',
//                      'DEBUG=145')
//CDAMSNAP DD     SYSOUT=X

DSN=CDAM_dsname

This parameter is used, as a retrieval criterion to obtain a desired CDAM according to CDAM name. To retrieve a particular CDAM, the ON DSN / ON TRNDSN statement must contain the DSN parameter defined with CDAM name withan asterisk instead of the two last ‘00’ characters. If the CDAM name is longer than 40 characters, define the DSN= parameter on the second line of the ON DSN / ON TRNDSN statement in the Decollation mission definition. For example:

ON DSN        = PREFIX=CTD.USR,
    DSN=CTD.USR.CTDCDAM.J69859.D0571613.S01.N0004*          
PRT COPIES    LVL    USER 
    PRINT/CDAM PARMS =                                      

If a Decollation mission definition is ordered by FTO, define the DSN parameter DSN as DSN=%%CDAM. In this case, the variable %%CDAM will be resolved by the CDAM name created by FTO in the current session, as follows:

ON DSN        = PREFIX=CTD.USR,                            
    DSN=%%CDAM                                              
PRT COPIES    LVL    USER                                   
    PRINT/CDAM PARMS =                                      

EAVUSE=OPT|NO

The EAVUSE parameter can be used as a CDAM parameter in PRINT/CDAM PARMS in a decollation mission definitions, and as a SUBSYS parameter in JCL cards.

When this parameter is specified in a JCL card, Control-D uses the dynamic allocation parameter EATTR=OPT|NO for allocation of the created CDAM files. If it is omitted, the EAVUSE#C parameter in the CTDPARM member is used by default.

When this parameter is specified in a decollation mission, Control-D uses the dynamic allocation parameter EATTR=OPT|NO for allocation of the created CDAM and Index files. If it is omitted, the EAVUSE#C parameter in the CTDPARM member is used by default for the CDAM files and the EAVUSE#V parameter in the CTVPARM member is used by default for the index files.

ENCODING={rprt_enc|NO}

This parameter specifies the character set used in the report. Although the report is written to CDAM in the original encoding, the decollation mission works with text translated into EBCDIC code.

If the encoding is not defined for an XML report, the encoding is taken from the XML header record. If the encoding is not specified in the XML header, the UTF-8 code is assumed according to the XML standard. If this parameter is not specified for a non-XML report, no translation is performed.

The list of supported encoding is located in the ENCODTBL member of the IOA IOAENV library.

ENCRYPT={YES | NO}

This parameter specifies whether the CDAM Encryption routine encrypts regular (non-JOBSDSN) data before it is written to the CDAM file. This parameter can be used as a CDAM parameter in PRINT/CDAM PARMS in decollation mission definitions, and as a SUBSYS parameter in JCL cards.

EXIT={YES | NO}

This parameter designates whether output processing Exit CTDX018 should be activated. This parameter can only be used when writing directly to a CDAM file. The default setting of EXIT is NO (that is, the exit is not activated). This default can be changed by the INCONTROL administrator. When EXIT is set to YES, the exit receives control for every line which is written to a CDAM file. For additional details, see CDAM User Exit CTDX018.

JOBID=Jnnnnn[nn]

This parameter can be used for retrieval purposes. The format is Jnnnnn or Jnnnnnnn where nnnnn[nn] is the JES job ID of the job which created the compressed sysout. JOBID can be 5 or 7 digits depending on the z/OS setting.

JOBNAME=name

This parameter can be used for retrieval purposes. The format is a 1 through 8 character valid jobname. It represents the job which created the compressed sysout.

LAST={YES|NO}

This parameter is used, along with other parameters, as a retrieval criteria to obtain the sysouts of the last job. The default value of this parameter is N (No).

If LAST is set to Y (Yes), Control-V retrieves (decollates) the SYSOUTs of the last execution of the job. For example:

ON DSN PREFIX=CDU08,DDNAME=REPOUT,LAST=YES

For the specific report decollating mission jobname, the last execution of the job which produced output on DD statement REPOUT is processed and its outputs from DD statement REPOUT (CDAM datasets) are decollated.

LINECT=number

This parameter can be used for reports without page control characters (machine or ASA reports). When printing without Control-V, the printer normally skips to a new page based on the value of the LINECT parameter of the OUTPUT statement. The same is true for Control-V. It breaks such reports into pages based on the value of the LINECT parameter. If the parameter is not specified for such reports, Control-V assumes that the value of LINECT is 100.

This parameter affects all reports. Even if a report has page control characters, a page break occurs after LINECT lines if control character ‘1’ is not detected.

This parameter should be specified in the CDAM parameters when writing directly to CDAM or in the PRINT/CDAM PARMS field when decollating from spool. For more information, read about parameter LINECT in PRINT/CDAM PARMS: Decollating Parameter (Decollating Mission)

OUTLIM=number

The OUTLIM parameter sets a limit on the number of records that can be written to a CDAM during decollation from a SYSOUT. If the limit is reached, the decollation mission will end immediately. No error message for this limit is issued. The remaining part of the SYSOUT will not be stored in CDAM.

The optional wish WD0699 does not limit the size of CDAM files written by decollation.

The OUTLIM parameter can be specified in the PRINT/CDAM PARMS field of any ON statement except ON DSN. If specified elsewhere (during a write operation), an error message is not produced and the parameter is ignored.

PCARCH={Y|N}

Specifies whether the report is (Y) or is not (N) archived (backed up) by Control-D/WebAccess Server after the report is transferred to a PC. For more information, see the description of modifying report attributes in the Control-D/WebAccess Server Administrator Guide.

PGMSTEP=name

This parameter may be used for retrieval. The format is a 1 through 8 character valid job step name. It represents the step in the job from which the compressed sysout has been created.

PREFIX=name

CDAM writes the sysout to sequential datasets. The PREFIX parameter specifies the high level datasets name qualifier. The name must be a valid dataset name qualifier of from 1 through 7 alphanumeric characters. It may consist of two parts separated by a period, but total length cannot exceed seven characters.

This parameter is optional. If omitted, the following occurs:

• If the file is created when writing directly to CDAM, the value specified in the Control-D installation parameter AMPREF in the CTDPARM member is used.

• If the file is created by Control-D decollation with ALLOCOPT=JOBSDSN1, the value specified in the Control-D installation parameter JB1PREF in the CTDPARM member is used.

• In all other cases (the file is created by Control-D decollation without ALLOCOPT, or with ALLOCOPT=ONEDSN or JOBSDSN2), the value specified in the Control-D installation parameter AMPREFD in the CTDPARM member is used.

The dataset names created by the CDAM are subject to regular security constraints imposed by the data center (using any standard security package or site-developed system). The dataset is allocated and opened using the standard system services, thus enforcing regular security considerations.

PROCSTEP=name

This parameter may be used for retrieval. The format is a 1 through 8 character valid procedure step name. It represents the JCL procedure step name from which the compressed sysout has been created.

PS={DOC1|CSET}

The PS parameter can be used to decollate PostScript output using the DOC1 or CompuSet product.

STEPNUM=nn

This parameter can be used for retrieval. The format is nn where nn is the relative number of the step from the beginning of the job (in hexadecimal format). It represents the step number in the job from which the compressed sysout has been created.

TIME=hhmm

This parameter can be used for retrieval. The format is hhmm representing the hour and minute when the compressed sysout was created.

TRANSTO=transformationtype

This parameter specifies the type of file to which the report is transformed when viewed using Control-D/Page On Demand (for example, PDF, TXT).

For example, if the CDAM parameter APA is set to YES (specifying an AFP report) and TRANSTO is set to PDF, when the AFP report is viewed using Control-D/Page On Demand, it is converted to a PDF file.

The file conversion occurs only if the appropriate conversion utility is installed.

For more information about the TRANSTO parameter, see the Control-D and Control-V chapter of the INCONTROL for z/OS Administrator Guide.

UNIT=name

The name of the unit on which the compressed SYSOUT is written. The name must be a valid (1 through 8 character) unit name within the system. The unit must be a disk and it can span any number of disk drives. The parameter is optional. The default name is defined by Control-D installation parameter AMUNIT.

VOLUMES=(nnnnn1,...nnnnn6)

The names of the volumes on which the compressed SYSOUT is written. The names must be a valid volume name within the system. The parameter is optional. The default name is defined by the Control-D installation parameter AMVOL.

XMLSEP=tagname

Defines an XML tag to be used for splitting an XML document into pages. The value tagname is case-sensitive. When XMLSEP is set to a value, the ASSOC parameter is set to XML. For CDAM decollation, the XMLSEP parameter must be specified only in the SUBSYS parameter of the DD statement creating the document. XMLSEP may be used only for EBCDIC reports.

CDAM Parameter Examples

//         EXEC  PGM=XXXX
//PRINT    DD    SUBSYS=(CDAM,'SYSOUT=A,PREFIX=J01','OUTLIM=100000')
//OUT      DD    SUBSYS=(CDAM,'SYSOUT=X')
//SYSPRINT DD    SYSOUT=X

//   EXEC  CICS
//SYSUDUMP DD SUBSYS=(CDAM,'SYSOUT=X,PREFIX=CICSDMP,BLOCKS=1000')

//S1OUT   OUTPUT ADDRESS=(‘ADR1,ADR2’,ADR),BUILDING=BLD,
//        FORMS=ABCDEFGH,PAGEDEF=PGDEF,FORMDEF=FRMDEF
//SYSUT2  DD   SUBSYS=CDAM,’CMPEXT=YES’),OUTPUT=(*.S1OUT)

Parameter DSN of the DD Statement

When a DD statement references a CDAM dataset, the value of the DSN parameter is not used as the CDAM dataset name. A new dataset name is created by CDAM. This parameter can be used for passing information to the CDAM. For more information see Special Use of Parameter DSN=ODATE.D Option.

Special Use of Parameter DSN=ODATE.D Option

The DSN parameter can be used by CDAM to force the date when writing directly to a CDAM file. As a default, the date of a CDAM file is taken from the computer clock (that is, the date of its creation). When the DSN parameter is in the following format, the CDAM dataset date is taken from the DSN field:

//XXX DD SUBSYS=(CDAM,'....'),DSN=ODATE.Dyyddd

where

• yy is the year

• ddd is the Julian date

It may be desirable to force a date in the following situations:

• The date can be used as a decollation criteria. When decollating from CDAM datasets using the ON DSN option, it is possible to specify the date as a parameter. The resulting decollation includes all sysouts of the job for that date (including multiple executions on the same day, abends and reruns).

• When different business dates run on the same system date, the decollation criteria may confuse sysouts of different business dates. To prevent this situation, the business date of the job may be forced as the CDAM dataset date.

The date force option is primarily designed for Control-M users who can automatically change the CDAM DSN for each business date using the AutoEdit facility. The special DSN=ODATE option is used to accommodate JCL syntax limitations. It is impossible to pass a symbolic procedure parameter to subparameters of a SUBSYS which are between quotes (all CDAM parameters are supplied between quotes).

//DEMO   PROC DATE=NONE
//STEP01 EXEC PGM=TEST
//DDNAME DD   SUBSYS=(CDAM,'PREFIX=CTDSYS'),DSN=ODATE.D&DATE

//JOBNAME JOB .....
//     EXEC DEMO,DATE=%%OYEAR.%%OJULDAY

Users of other scheduling systems can change the date of a CDAM file to the business date using facilities provided by those products.

The report decollating mission parameters for decollating CDAM datasets created in all the executions of the job on the same business date should be:

ON DSN    PREFIX=CTDSYS,DATE=999

999 is automatically replaced with the original Julian scheduling date of the report decollating mission.

The report decollating mission parameters for decollating CDAM datasets which are created in the last execution of the job on the same business date should be:

ON DSN    PREFIX=CTDSYS,DATE=999,LAST=YES

If for some reason, a CDAM dataset is not created for that job on that business date, reports are not selected. If only LAST=YES is used, reports from the previous business date are selected.

CDAM Logic

CDAM writes the compressed sysout to a sequential dataset. Each sysout may span one or more datasets. The datasets are allocated on the unit specified in the CDAM parameters, without secondary allocation parameters. The workflow of CDAM is as follows:

• When the application program performs the first write (PUT) operation, CDAM tries to allocate a dataset on the specified (or default) unit using the specified (or default) blocks parameter and the RLSE option.

• The dataset is allocated and opened through standard system facilities, and passes through all security and allocation verifications performed in the operating system. In case of failure, normal system messages are produced and the job terminates.

• The dataset name is cataloged immediately at the time of creation. The dataset name created by CDAM conforms to the naming conventions described below.

• When CDAM uses all the available space in the first "logical" extent, it does not abend on SB37. It tries to allocate another logical extent (see below for naming conventions). A logical extent is a standard sequential file from the operating system point of view. The attempted allocation size is twice the amount of the previous logical extent size. The logical extent may be on a different disk drive in the same unit.

  If allocation fails (that is, a space in the specified size cannot be found), the CDAM attempts half of the previous size and continues to do so until the allocation succeeds. Therefore, CDAM abends on SB37 only when the last single free track in the specified unit is full, that is, there is no remaining space in the entire unit.

  In this way, CDAM makes use of otherwise unusable areas on the disks. The disk normally contains unused tracks which cannot be used by the standard dataset allocation algorithm. These areas can be used by CDAM. For example, a CDAM dataset could be allocated as follows:

  This example is exaggerated to illustrate the CDAM allocation algorithm.

  Table 278 CDAM Dataset Allocation – Example

  Logical Extent	No. of Tracks
  1st logical extent	50 tracks
  2nd logical extent	100 tracks
  3rd logical extent	50 tracks
  4th logical extent	25 tracks
  5th logical extent	6 tracks
  6th logical extent	1 track
  7th logical extent	1 track
  8th logical extent	1 track
  9th logical extent	1 track

• When the ddname of the sysout is deallocated (usually at the end of the step), the remaining free tracks in the last allocated logical extent are released for general use (since the dataset is allocated using parameter RLSE).

When a compressed sysout is read by CDAM, the record format, block size and the record length of the dataset are retrieved. The report takes the original LRECL, BLKSIZE and RECFM specifications (from the ACB/DCB) as it had when produced by the application program.

CDAM Dataset Naming Conventions

A CDAM dataset conforms to the following naming conventions:

PREFIX.JOBNAME.JOBID.DATETIME.STEP#.FILEID

Table 279 CDAM Dataset Naming Conventions

Multijob CDAM Datasets

A multi-job CDAM dataset differs from a regular CDAM dataset in that it contains sysouts of many jobs instead of only one job.

The allocation algorithm of a multi-job CDAM dataset allocates a large specified space for the dataset. All the job’s sysouts are written to the dataset. As soon as a job is decollated, its sysouts are available for online viewing.

However, unlike regular CDAM allocation options, the file remains allocated to the Control-D monitor. The monitor adds additional SYSOUTs of jobs to the same file. When the first logical extent of the CDAM file is full, CDAM allocates a second logical extent. CDAM continues writing to the logical extent until the end of the processed job.

Next, the file (which now contains sysouts of many jobs) is deallocated, and the remaining space in the second extent is freed. When a new job is processed, a new multi-job CDAM dataset is allocated with the specified space (as first logical extent) and the process resumes.

This type of CDAM dataset combines the benefits of one large pre-allocated reports database designated to contain many reports, with the benefits of dynamic allocation of needed space when the reports database is full.

Multi-job CDAM files, created by using CDAM parameter ALLOCOPT=JOBSDSN1 or ALLOCOPT=JOBSDSN2, cannot be used as input for a report decollating mission.

Example of Decollating Parameters

ON CLASS A      
PRINTING PARAMETERS ALLOCOPT=JOBSDSN1,BLOCKS=1000,PREFIX=CTDPRDJ
  WHEN - no data in the WHEN statement
        DO USER    PRODCNTL
        DO NAME    PRODUCTION MSGCLASS
        DO BACKUP  BCK0031D

It is highly recommended to use parameters BLOCKS and PREFIX in conjunction with parameter ALLOCOPT=JOBSDSNx. If parameter BLOCKS is not specified, the default Control-D installation parameter AMBLK#D is used. This parameter value may be too small, resulting in one JOBSDSN dataset containing a small number of jobs.  

If parameter PREFIX is not specified, the default prefix is taken from the Control-D installation parameter AMPREFD (unless ALLOCOPT=JOBSDSN1, in which case the default prefix is taken from the installation parameter JB1PREF). Using this default prefix may cause regular CDAM datasets and multi-job CDAM datasets to become intermixed.

The PREFIX is the unit of integrity of multi-job CDAM datasets. If two (or more) report decollating missions with ALLOCOPT=JOBSDSNx refer to the same CDAM prefix, the sysouts are written to the same multi-job CDAM dataset. Different decollating missions with ALLOCOPT=JOBSDSNx can refer to different prefixes. In this case, each one is directed to a different multi-job CDAM dataset.

When to Use Each ALLOCOPT Option

For regular (large volume) reports, it is recommended not to use the ALLOCOPT options. The best performance and results are achieved with the "classical" CDAM technique.

ALLOCOPT=JOBSDSN2 should be used for decollating many short sysouts, where each sysout has different printing characteristics (for example, different CHARS). Since a SYSDATA entry is developed for each sysout, the printing characteristics are not lost. An advantage to this option is the efficient use of CDAM space since, many short reports are compressed into a combined area (without any unused free space).

ALLOCOPT=JOBSDSN1 should be used for decollating many short sysouts, where each sysout has the same printing characteristics. (If they differ only by the type of page control characters, machine or ASA, they can be treated similarly.) An example is generic decollating of job MSGCLASS outputs. Since only one SYSDATA entry is developed for each job, only a limited amount of space is used in the User Reports List files. Another important advantage is the efficient use of CDAM space, since many short reports are compressed to a combined area (without any unused free space). This method is the most space-efficient and results in faster decollation.

Use ALLOCOPT=ONEDSN under the same conditions as ALLOCOPT=JOBSDSN1 when a separate CDAM dataset is required for each job.

CDAM User Exit CTDX018

CDAM User Exit CTDX018 is activated when the CDAM expression EXIT=YES is specified. The exit, which should be in a LINKLIST concatenation, receives control for every line written to the CDAM file.

On first invocation, the exit can specify that CDAM must perform one of the following functions:

• Write the file to a CDAM dataset (as normally done).

• Suppress CDAM processing, leaving the exit responsible for processing the report.

Alternatively, on any invocation after the first, the exit can modify the contents (and optionally the length) of the report line before it is written to the CDAM file. If the length is set to zero, the line is not written to the CDAM file, which is equivalent to suppressing the line.

As a further alternative, the exit can, on the first or any subsequent invocation, perform one of the following functions:

• Activate other programs, as described in Example 1.

• Add lines to the report, as described in Example 2.

The following examples illustrate these functions.

CDAM Maintenance Utility CTDAMUTI

Utility CTDAMUTI is used to copy, move and delete CDAM datasets. (CTDAUTI is the program name for utility CTDAMUTI.)

The CDAM dataset is composed of one or more system datasets which are logically connected. They appear to the application program as one sequential dataset only when they are interfaced using CDAM (using parameter SUBSYS).

Standard system maintenance utilities are able to function only on one logical extent (system dataset). To delete an entire CDAM dataset, the user must physically delete all the logical extents of the dataset. Utility CTDAMUTI enables the user to delete all extents of a CDAM dataset using regular CDAM parameters.

Another important use of utility CTDAMUTI is for emergency situations. If for some reason, the CDAM subsystem cannot be started and it is therefore impossible to read the CDAM datasets using the normal SUBSYS parameter, this utility can decompress the sysout to its original (non-compressed) form even if the CDAM subsystem is not active.

If DD statement UTICOPY is present in the job which activates utility CTDAMUTI, output is written to the file referenced by this DD statement instead of to the SPOOL. Utility CTDAMUTI sets the DCB parameters of this output file according to the original report, that is,

• RECFM is set to VB, or VBA, or VBM (according to the original report).

• LRECL is set to 32756.

• BLKSIZE is set to 32760.

If ‘DUMMY’ is specified in the UTICOPY DD statement, the CTDAMUTI utility lists the CDAM files that fit specified selection criteria.

Activating the Utility

//           EXEC CTDAMUTI
//DAMUTIN    DD   *
  PARAMETERS
//

Parameter Format

function
dataset identification parameters (selection criteria)

where function can be:

• DELETE: Delete one or more CDAM datasets conforming to the identification parameters.

• COPY: Copy one or more CDAM datasets conforming to the identification parameters to a sysout on the spool (decompressed).

• MOVE: Move (copy and delete) one or more CDAM datasets conforming to the identification parameters to a sysout on the spool (decompressed).

• RECOVER: Perform the COPY function (described above) but add a line containing CDAM characteristics for each processed file. This parameter is useful when processing multi-job CDAM datasets. see Using Utility CTDAMUTI on Multi-job Datasets.

The dataset identification parameters can be any valid CDAM subsystem parameters. They should be specified between columns 1 - 71 and should be separated by commas.

When using ALLOCOPT=JOBSDSN1 only the following parameters are used in the selection criteria:

• JOBNAME

• JOBID

• SYSOUT

• DATE

When using ALLOCOPT=JOBSDSN2 only the following parameters are used in the selection criteria:

• JOBNAME

• JOBID

• SYSOUT

• DATE

• DDNAME

• PGMSTEP

//   EXEC  CTDAMUTI
//DAMUTIN  DD *
  DELETE
  JOBNAME=J01MUTP,JOBID=J00345,
  DATE=298,
  PREFIX=J01

//   EXEC  CTDAMUTI
//DAMUTIN  DD *
  COPY
  DATE=298,
  PREFIX=J01

//   EXEC  CTDAMUTI
//DAMUTIN  DD *
  RECOVER
  PREFIX=JB1,
  DATE=298,
  ALLOCOPT=JOBSDSN1

Using Utility CTDAMUTI on Multi-job Datasets

When activating utility CTDAMUTI on multi-job CDAM datasets (that is, datasets created using parameter ALLOCOPT=JOBSDSNx), use the following rules:

Table 280 Rules Used when Activating Utility CTDAMUTI on Multi-Job CDAM Datasets

Because of the above limitations, the same prefix should not be used for regular CDAM datasets and multi-job datasets.

Migrated CDAM Datasets

The Control-V migration process migrates CDAM datasets to various storage media (optical disk, cartridge, DASD, and so on). CDAM datasets migrated by a "primary" migration mission can be viewed and/or printed using Control-V online viewing functions. The IOA Archive server is used to access migrated CDAM datasets for online viewing and immediate printing.

IOA Archive Server

The IOA Archive server is a started task that provides services for online viewing and immediate printing. These services are used whenever data is required from a migrated CDAM or index dataset which does not reside on DASD.

Communication between the online viewing process and the IOA Archive server is accomplished using cross memory services.

The IOA Archive server receives data retrieval requests from online viewing users. Data from various migrated CDAM datasets that reside on different media may be requested. The server implements request queuing and data caching mechanisms to optimize available resource utilization and return requested data as quickly as possible. For more information about the IOA Archive server, see the Control-D and Control-V chapter of the INCONTROL for z/OS Administrator Guide.

Media and Resource Management

The media and resources available for use by the IOA Archive server are defined by installation parameters in member IOASPRM. The definition of media and resources differs for various media types, but includes the following:

• Media information (name, type, and so on).

• Information about each resource (device, session, and so on) known to the server and the desired status of the resource when the server is started.

• An owned or shared flag (dedicated versus dynamic) which indicates if the resource is dedicated to the server, or is dynamically assigned when needed and released when no server requests are pending.

The initial status of resources defined in the installation parameters can be changed during processing by operator commands.

Resources required for the IOA Archive server should be online and ready when requested. Services provided by the IOA Archive server degrade or stop if a required resource is not available. In this case, users requesting online viewing or immediate printing may be left waiting for data from migrated CDAM datasets.

OSS Media

The DataWare/ROSs/OSS Storage System (OSS) utilizes 3490 emulation. Its resources are 3490 devices which are referred to by device number. These devices should be explicitly defined to the IOA Archive server (by device number) and dedicated to the server.

Devices that temporarily need to be used by other jobs or by started tasks should be disconnected from the IOA Archive server by an operator command.

The IOA Archive server uses a queuing mechanism to minimize platter switching.

FTK Media

The resources defined for FTK media are the number of sessions the IOA Archive server has with the FileTek Storage Machine (SM). For each data set that is viewed or printed from the SM, the FTK media activates a logical device that opens a session with the SM and retrieves all the necessary data.

The maximum number of logical devices is defined in IOASPRM by parameter MAXCONN.

The IOA Archive server uses a queuing mechanism to retrieve together all the data from the same dataset.

CART Media

The resources defined for CART media are actual 3490 devices. These devices may be defined explicitly by specifying their device numbers, or implicitly by specifying the quantity of devices available for the IOA Archive server. It is also possible to define whether the devices are owned by the server (DEDICATED), or are shared by the server and other jobs based on need (DYNAMIC).

The IOA Archive server uses a queuing mechanism to minimize volume switching.

Dedicated Device Method

Using this method, the IOA Archive server allocates the devices (which may be defined explicitly, or implicitly by quantity) during initialization and de-allocates them when an appropriate operator command is issued. This guarantees the number of volumes which can be accessed concurrently for online viewing and immediate printing requests.

Devices that temporarily need to be used by other jobs or by started tasks should be disconnected from the IOA Archive server by an operator command.

This method is recommended to ensure a rapid response time when many requests are issued to different volumes.

Dynamic Device Method

Using this method, the server allocates devices (up to the "start quantity" defined in the installation parameters) when a request is received. When no requests are pending, the devices can be used by other jobs or started tasks.

Based on the level of service required and the number of pending requests, the operator can increase (up to the "maximum quantity" defined in the installation parameters) or decrease the number of devices the server tries to use.

This method provides no guarantee that devices are available to the IOA Archive server when needed. If many requests are pending and not enough devices are available, response time for users degrades.

This method is recommended when the server is often idle, or when there is a shortage of 3490 drives.

CDAM Encryption

Many organizations require that information that is either critical to their operations or to their customers’ vital interests be managed in a secure manner. Industrial standards, such as PCI and SOX, require that Control-D reports be encrypted. The CDAM Encryption feature enables Control-D for z/OS to encrypt data written into CDAM files and to decrypt data read from CDAM files.

You can activate the Control-D CDAM Encryption with a:

• General default setting.

• Job specific setting.

• Decollation mission setting.

Control-D CDAM Encryption Activation

This section describes how you can activate the Control-D CDAM Encryption routine.

General Default Settings

You have the following options for specifying the default encryption settings for CDAM files:

• For CDAM files that are created either by a single decollation or application program, use the AMENCRPT parameter in the CDAM section of the CTDPARM member.

• For multi-job (JOBSDSN) CDAM files, created by the Control-D monitor, and containing the results of multiple decollations, (each with possibly different encryption types) use the AMENCJDS parameter in the CDAM section of the CTDPARM member.

For more information about these parameters, see the CDAM parameter descriptions in the INCONTROL Installation Guide: Installing.

Job Specific Setting

To specify whether a specific job creates an encrypted CDAM file, use the ENCRYPT parameter in the CDAM SUBSYS parameter field of the corresponding DD statement of the job.

For more information about this parameter, see "ENCRYPT={YES | NO}" in CDAM Control Parameters.

Decollation Mission Setting

To specify whether a specific decollation mission creates an encrypted CDAM file, use the ENCRYPT parameter in the PRINT/CDAM PARMS field of the decollation mission definition.

For more information about this parameter, see "ENCRYPT={YES | NO}" in CDAM Control Parameters.

Parameter Summary

CDAM encryption is specified with the parameters shown in Table 281.

Table 281 CDAM Encryption Parameter

You can choose to use the Control-D supplied CDAM Encryption or your own in-house developed encryption algorithm.

User Exit CTDX029

The CTDX029 user encryption exit is located in the IOA LOAD library or MVS LINKLIST library. It must be loaded into the CSA during the subsystem start. In order to replace the user encryption exit, the CDAM subsystem must be stopped and restarted.

The CTDX029 user exit is activated for:

• Encryption: During the creation of a CDAM file that is specified for encryption by CTDX029.

• Decryption: During the retrieval of a CDAM file that was encrypted by CTDX029.

The CTDX029 user encryption exit can be called with one of the following call functions:

• INIT

• PROCESS

• TERM

During the creation of a CDAM file, when CTDX029 is called, with the INIT function, it places a return code indicating that the file will:

• Be encrypted by the Control-D supplied CDAM Encryption routine.

• Not be encrypted, overriding other parameters specifications.

• Be encrypted by the Control-D supplied CDAM Encryption routine with a key supplied by the exit.

• Be encrypted by the exit.

The return code indicator is saved in the CMP block. The indicator determines the method of decryption. Any administrative data that is returned is also saved in this block. During retrieval this data is accessible. The maximum length of this data is specified with the AMENCDLN parameter in CTDPARM.

If the last decision has been returned, the exit is called with the PROCESS function for each block, before the block is written to the file. The exit returns the encrypted data block and the length of encrypted data.

During the retrieval of a CDAM file, when CTDX029 is called, with the INIT function, it places a return code indicating that the file will be decrypted by the

• Control-D supplied CDAM Encryption routine with a key supplied by the exit.

• CTDX029 exit.

In the second case, the exit is called with the PROCESS function for each block, after the block is read from the file. The exit returns the decrypted data block and the length of decrypted data.

It is possible that the user exit algorithm will increase the length of the encrypted data. Use the AMENCFRE parameter in CTDPARM for specifying additional buffer length.

When the exit is called with TERM function, the exit releases all the resources that it used processing the file.

Since the user encryption exit must be completely backward compatible, it is possible to store the user exit version in the data for decryption process.

For more information about the AMENCDLN and AMENCFRE parameters, see the CDAM parameter descriptions in the INCONTROL Installation Guide: Installing.

Sample Exit That Supplies a User Key

The CTDX029K member in the IOA SAMPEXIT library contains a sample exit for returning a 24-byte key. The key would be used by the CDAM Encryption routine for encryption and decryption.

It also communicates with CDAM (via a return code for the INIT call) not to call the exit for processing blocks.

Sample Exit that Implements a User Algorithm

The CTDX029B member in the IOA SAMPEXIT library contains a sample exit that contains a simple algorithm. The algorithm exchanges high and low words in every double word in block. The customers can implement their own encryption algorithm.

In this case the exit communicates with CDAM (via a return code for the INIT call) to call the exit for each and every block.

An additional buffer may be required to return the encrypted/decrypted block, if the algorithm changes the length of the block