Creating a HOLD File

How to:

You can use the HOLD command to create report output files for a range of purposes:

If your environment supports the SET parameter SAVEMATRIX, you can preserve the internal matrix of your last report in order to keep it available for subsequent HOLD, SAVE, and SAVB commands when the request is followed by Dialogue Manager commands. For details on SAVEMATRIX, see the Developing Applications manual.

Syntax: How to Create a HOLD File

From a report request, use

ON TABLE HOLD [AS filename] [FORMAT fmt] [DATASET dataset]
       [MISSING {ON|OFF}][VIA program]
       [PERSISTENCE {STAGE|PERMANENT}]

or

hold_field HOLD [AS filename] [FORMAT fmt] [DATASET dataset]
       [MISSING {ON|OFF}][VIA program]
       [PERSISTENCE {STAGE|PERMANENT}]

After a report is executed, use

HOLD [AS filename] [FORMAT fmt] [DATASET dataset]
      [MISSING {ON|OFF}][VIA program]
      [PERSISTENCE {STAGE|PERMANENT}]

where:

HOLD
Extracts and saves report output. BINARY is the default format used when the HOLD command is issued without an explicit format. The output is saved with an associated Master File.

Note: Change the default output format to ALPHA by issuing the SET HOLDFORMAT command.

hold_field
Is the name of the last display field in the request.
AS filename
Specifies a name for the HOLD file. If you do not specify a file name, HOLD becomes the default. Since each subsequent HOLD command overwrites the previous HOLD file, it is advisable to code a distinct file name in each request to direct the extracted data to a separate file, thereby preventing it from being overwritten by the next HOLD command.

The name can contain up to the maximum number of characters supported by your operating system. For information, see the section Naming a Master File in the Describing Data manual.

FORMAT fmt
Specifies the format of the HOLD output file. BINARY is the default format.
  • To display as a webpage, choose: HTML, HTMTABLE, DHTML
  • To display as a printed document, choose: PDF, PS
  • To use in a text document, choose: ALPHA, DOC, WP
  • To use in a spreadsheet application, choose: DIF, EXCEL, EXL97, EXL2K [PIVOT], LOTUS, SYLK
  • To use in a database application, choose: COMMA, COM, COMT, DATREC, DFIX, DB2, FOCUS, SQL, SQLORA, SQLDBC, TAB, TABT, XFOCUS
  • To use with a 3-GL program, choose: INTERNAL
  • To use for additional reporting, choose: ALPHA, BINARY, FOCUS
  • To use as a transaction file for modifying a data source, choose: ALPHA, BINARY
  • To use for interactive analysis without connection to a FOCUS, choose: AHTML

For details about all available formats, see Choosing Output File Formats.

dataset

Can be a fully-qualified data set or file name or an n-part name (app/.../filename.ext).

You can specify a data set or file to contain the report output within the request itself, rather than relying on an external or default specification. This allows you to place a permanent hold file in any folder, directory or data set that you can write to, whether or not that location is included in your APP PATH. The accompanying HOLD Master File will have the DATASET attribute pointing to the file that was generated.

The case in which the data set name is added in the Master File depends on the value of the FILECASE parameter. By default, lowercase is used. The actual data set is created with its name in the case that conforms to the standards of your operating environment.

Note:

  • On z/OS, the file cannot already exist or be allocated when the HOLD command is issued. Therefore, If the file already exists you must free the allocation and then delete the file before running the request.
  • You can use a USS naming convention for the DATASET attribute to store the file in the USS environment (for text output types).
MISSING
Controls whether fields with the attribute MISSING=ON in the Master File are carried over into the HOLD file. MISSING ON is the default attribute. If the HOLD command specifies MISSING OFF, fields with the MISSING attribute are not carried over. For related information, see Handling Records With Missing Field Values. Also see the Developing Applications manual for the SET HOLDMISS, SET NULL, and SET HNODATA parameters, which control how missing values are propagated to alphanumeric and comma-delimited files.
VIA program
Calls a user-coded program to create the extract file. BINARY is the default format; ALPHA format is also available. Other formats are not available when you use a program with the HOLD command.
PERSISTENCE

Applies only to Relational HOLD files (FORMAT sqlengine). Specifies how to create intermediate tables that will be used only during UPLOAD and EBL requests to accelerate performance by keeping all processing on the DBMS server instead of downloading data into a HOLD file. The actual type of the intermediate table will be determined at run time, based on specific DBMS-supported features and the data-populating mechanisms being used. Valid values are:

  • STAGE. Will create either a Volatile or GLOBAL TEMPORARY table, for a DBMS that supports that functionality. For a DBMS that does not support that functionality, a message will display and the table will not be created.
  • PERMANENT. Will create a regular SQL table with a uniquely-generated name that will be used in the request and will be available for further use after the request ends, but will be dropped at the end of the session. This is the default value for PERSISTENCE for HOLD FORMAT sqlengine.

Syntax: How to Create HOLD Files From Hot Screen

From the FOCUS command line or from Hot Screen, use the following after the report is executed

HOLD [AS filename][FORMAT fmt][MISSING {ON|OFF}][VIAprogram]

where:

fmt
Can be ALPHA, BINARY, DIF, SYLK, WP, INTERNAL, or FOCUS. If you omit the format, the default HOLD format (BINARY) is used.

You can issue HOLD from the Hot Screen command line at any time while a report is displayed and on any page of the report. Regardless of the page from which you issue the command, the entire report is saved, and a data source and Master File are created for that report (just as when you issue the HOLD command from within a TABLE request, or after exiting Hot Screen).

You can issue multiple HOLD commands for a single TABLE request; however, once you specify the FOCUS format with a HOLD command from Hot Screen, you cannot issue another HOLD command during that Hot Screen session.

Note that you cannot use the SAVE or SAVB commands from Hot Screen. You must include these commands in a report request, or issue them from the FOCUS command level after exiting Hot Screen.

Example: Using DATASET for HOLD

The following request generates the file ggsum.ftm in the application named test1.

APP HOLD test1
TABLE FILE GGSALES                 
SUM UNITS DOLLARS                  
BY CATEGORY                        
BY PRODUCT                         
ON TABLE HOLD AS GGCOMT FORMAT COMT
DATASET test1/ggsum.ftm            
END                                

The generated Master File includes the DATASET attribute.

FILENAME=GGCOMT  , SUFFIX=COMT    ,                        
 DATASET=test1/ggsum.ftm (LRECL 80 RECFM V, $              
  SEGMENT=GGCOMT, SEGTYPE=S2, $                            
    FIELDNAME=CATEGORY, ALIAS=E01, USAGE=A11, ACTUAL=A11, $
    FIELDNAME=PRODUCT, ALIAS=E02, USAGE=A16, ACTUAL=A16, $ 
    FIELDNAME=UNITS, ALIAS=E03, USAGE=I08, ACTUAL=A08, $   
    FIELDNAME=DOLLARS, ALIAS=E04, USAGE=I08, ACTUAL=A08, $ 

The following request generates the data set USER1.GGHOLD.FTM on z/OS.

TABLE FILE GGSALES                 
SUM UNITS DOLLARS                  
BY CATEGORY                        
BY PRODUCT                         
ON TABLE HOLD AS GGCOMT FORMAT COMT
DATASET user1.gghold.ftm          
END                                

The generated Master File includes the DATASET attribute.

FILENAME=GGCOMT  , SUFFIX=COMT    ,                         
 DATASET=user1.gghold.ftm (LRECL 80 RECFM V, $             
  SEGMENT=GGCOMT, SEGTYPE=S2, $                             
    FIELDNAME=CATEGORY, ALIAS=E01, USAGE=A11, ACTUAL=A11, $ 
    FIELDNAME=PRODUCT, ALIAS=E02, USAGE=A16, ACTUAL=A16, $  
    FIELDNAME=UNITS, ALIAS=E03, USAGE=I08, ACTUAL=A08, $    
    FIELDNAME=DOLLARS, ALIAS=E04, USAGE=I08, ACTUAL=A08, $  

Syntax: How to Set the Default HOLD Format

SET HOLDFORMAT = {BINARY|ALPHA}

or

ON TABLE SET HOLDFORMAT {BINARY|ALPHA}

where:

BINARY
Sets the default HOLD file format to BINARY.
ALPHA
Sets the default HOLD file format to ALPHA.

Example: Extracting Data to a HOLD File

The following request extracts data from the EMPLOYEE data source and creates a HOLD file.

TABLE FILE EMPLOYEE
SUM CURR_SAL AND ED_HRS
BY DEPARTMENT
LIST CURR_SAL AND ED_HRS AND BANK_ACCT
BY DEPARTMENT
BY LAST_NAME BY FIRST_NAME
ON TABLE HOLD
END

The following message appears:

NUMBER OF RECORDS IN TABLE=  12 LINES=     12

You then see the message:

HOLDING...

To display the report generated by this request, either issue a report request against the HOLD file or issue the RETYPE command.

Tip: If you wish to view the information in the HOLD Master File before reporting against it, you can issue the query command ? HOLD.

Syntax: How to Query a HOLD Master File

If the HOLD format option you select creates a Master File, you can issue the following command to display the fields, aliases, and formats in the HOLD Master File:

? HOLD

This command shows field names up to 32 characters. If a field name exceeds 32 characters, a caret (>) in the 32nd position indicates a longer field name.

If you have renamed the HOLD file using AS filename, use the following syntax:

? HOLD filename

Tip: You must issue the ? HOLD query in the same session in which the HOLD file is created.

Example: Reporting Against a HOLD Master File

In the following HOLD file, the formats shown are the values of the FORMAT attribute. You can see the values of the ACTUAL attribute by displaying the HOLD Master File using TED or any text editor. USAGE and ACTUAL formats for text fields specify only the length of the first line of each logical record in the HOLD file. The USAGE format is the same as the field format in the original Master File. The ACTUAL format is rounded up to a full (internal) word boundary, as is done for alphanumeric fields.

The following request contains the query command ? HOLD, which displays the fields, aliases, and formats in the associated Master File and creates a HOLD file.

TABLE FILE EMPLOYEE
SUM CURR_SAL AND ED_HRS
BY DEPARTMENT
LIST CURR_SAL AND ED_HRS AND BANK_ACCT
BY DEPARTMENT
BY LAST_NAME BY FIRST_NAME
ON TABLE HOLD
END
 
? HOLD

The output is:

NUMBER OF RECORDS IN TABLE=     12    
LINES=        
12
DEFINITION OF HOLD FILE: HOLD
FIELDNAME
ALIAS
FORMAT
DEPARTMENT
E01
A10
CURR_SAL
E02
D12.2M
ED_HRS
E03
F6.2
LAST_NAME
E04
A15
FIRST_NAME
E05
A10
LIST
E06
I5
CURR_SAL
E07
D12.2M
ED_HRS
E08
F6.2
BANK_ACCT
E09
I9S

You can now issue the following report request against the HOLD file:

TABLE FILE HOLD
PRINT E07 AS 'SALARY OF,EMPLOYEE' AND LAST_NAME AND FIRST_NAME
BY HIGHEST E03 AS 'TOTAL,DEPT,ED_HRS'
BY E01
BY HIGHEST E08 AS 'EMPLOYEE,ED_HRS'
END

The output is:

TOTAL                                                                     
DEPT                EMPLOYEE        SALARY OF                             
ED_HRS  DEPARTMENT  ED_HRS          EMPLOYEE   LAST_NAME        FIRST_NAME
------  ----------  --------        ---------  ---------        ----------
231.00  MIS            75.00       $21,780.00  BLACKWOOD        ROSEMARIE 
                       50.00       $18,480.00  JONES            DIANE     
                       45.00       $27,062.00  CROSS            BARBARA   
                       36.00       $13,200.00  SMITH            MARY      
                       25.00        $9,000.00  GREENSPAN        MARY      
                         .00       $18,480.00  MCCOY            JOHN      
120.00  PRODUCTION     50.00       $16,100.00  MCKNIGHT         ROGER     
                       30.00       $26,862.00  IRVING           JOAN      
                       25.00       $11,000.00  STEVENS          ALFRED    
                       10.00        $9,500.00  SMITH            RICHARD   
                        5.00       $21,120.00  ROMANS           ANTHONY   
                         .00       $29,700.00  BANNING          JOHN

Information Builders