Creating a Structured HOLD File

How to:

Reference:

Structured HOLD Files facilitate migration of data sources and reports between operating environments.

Other HOLD formats capture data from the original sources and may retain some implicit structural elements from the request itself. However, they do not propagate most of the information about the original data sources accessed and their inter-relationships to the HOLD Master File or data source. Structured HOLD files, however, extract the data to a structure that parallels the original data sources. Subsequent requests against the HOLD file can use these retained data relationships to recreate the same types of relationships in other environments or in other types of data sources.

A Structured HOLD File can be created in ALPHA, BINARY, or FOCUS format:

In all cases the HOLD file contains all of the original segment instances required to provide the complete report based on the TABLE request itself. Regardless of the display command used in the original request (PRINT, LIST, SUM, COUNT), the Structured HOLD File is created as if the request used PRINT. Aggregation is ignored.

The HOLD file contains either all of the fields in the structure identified by the request that are used to satisfy the request, or all of the display fields and BY fields. The file does not contain DEFINE fields not specifically referenced in the request. It does contain all fields needed to evaluate any DEFINE fields referenced in the request.

Structured HOLD files are only supported for TABLE and TABLEF commands. They can be created anywhere a HOLD file is supported. You must activate Structured HOLD files in a specific request by issuing the ON TABLE SET EXTRACT command in the request prior to creating the Structured HOLD File.


Top of page

x
Syntax: How to Activate Structured HOLD Files for a Request
ON TABLE SET EXTRACT {ON|*|OFF}

where:

ON
Activates Structured HOLD Files for this request and extracts all fields mentioned in the request.
*
Activates Structured HOLD Files for this request and indicates that a block of extract options follows. For example, you can exclude specific fields from the Structured HOLD File. For information, see How to Specify Options for Generating Structured HOLD Files.
OFF
Deactivates Structured HOLD files for this request. OFF is the default value.

Top of page

x
Syntax: How to Create a Structured HOLD File

Before issuing the HOLD command, activate Structured HOLD Files for the request by issuing the ON TABLE SET EXTRACT command described in How to Activate Structured HOLD Files for a Request. Then issue the HOLD command to create the Structured HOLD File:

[ON TABLE] {HOLD|PCHOLD} [AS name] FORMAT {ALPHA|BINARY|FOCUS}

where:

name
Is the name of the HOLD file. If omitted, the name becomes HOLD by default.
FORMAT
Is ALPHA, BINARY or FOCUS.

Note: You can issue a SET command to set the default HOLD format to either ALPHA or BINARY:

SET HOLDFORMAT=ALPHA
SET HOLDFORMAT=BINARY

Top of page

x
Syntax: How to Specify Options for Generating Structured HOLD Files

To specify options for creating the extract, such excluding specific fields, use the * option of the SET EXTRACT command:

ON TABLE SET EXTRACT *
EXCLUDE = (fieldname1, fieldname2, fieldname3 , ..., fieldnamen),$
FIELDS={ALL|EXPLICIT},$
ENDEXTRACT
ON TABLE HOLD AS name FORMAT {ALPHA|BINARY|FOCUS}

where:

EXCLUDE=(fieldname1, fieldname2, fieldname3,..., fieldnamen)
Excludes the specified fields from the HOLD file.
,$
Is required syntax for delimiting elements in the extract block.
ALL
Includes all real fields and all DEFINE fields that are used in running the request.
EXPLICIT
Includes only those real fields and DEFINE fields that are in the display list or the BY sort field listing. DEFINE fields that are not explicitly referenced, and fields that are used to evaluate DEFINEs, are not included.
ENDEXTRACT
Ends the extract block.



Example: Creating a Structured HOLD File in ALPHA Format
TABLE FILE EMPLOYEE
PRINT LAST_NAME FIRST_NAME JOBCODE ED_HRS
BY DEPARTMENT
BY HIGHEST SALARY
ON TABLE SET EXTRACT ON
ON TABLE HOLD FORMAT ALPHA
END

This request produces the following HOLD Master File:

FILENAME=HOLD    , SUFFIX=FIX     , $
  SEGMENT=EMPINFO, SEGTYPE=S0, $
    FIELDNAME=RECTYPE, ALIAS=R, USAGE=A3, ACTUAL=A3, $
    FIELDNAME=LAST_NAME, ALIAS='LN', USAGE=A15, ACTUAL=A15, $
    FIELDNAME=FIRST_NAME, ALIAS='FN', USAGE=A10, ACTUAL=A10, $
    FIELDNAME=DEPARTMENT, ALIAS='DPT', USAGE=A10, ACTUAL=A10, $
    FIELDNAME=ED_HRS, ALIAS='OJT', USAGE=F6.2, ACTUAL=A06, $
  SEGMENT=PAYINFO, SEGTYPE=S0, PARENT=EMPINFO, $
    FIELDNAME=RECTYPE, ALIAS=1, USAGE=A3, ACTUAL=A3, $
    FIELDNAME=SALARY, ALIAS='SAL', USAGE=D12.2M, ACTUAL=A12, $
    FIELDNAME=JOBCODE, ALIAS='JBC', USAGE=A3, ACTUAL=A03, $

Note the RECTYPE field generated for ALPHA or BINARY Structured HOLD files. Each record in the HOLD file begins with the RECTYPE to indicate the segment to which it belonged in the original structure. The root segment has RECTYPE=R. The RECTYPEs for other segments are sequential numbers assigned in top to bottom, left to right order.

Following are the first several records in the HOLD file:

R  STEVENS        ALFRED    PRODUCTION 25.00
1      11000.00A07
1      10000.00A07
R  SMITH          MARY      MIS        36.00
1      13200.00B14
R  JONES          DIANE     MIS        50.00
1      18480.00B03
1      17750.00B02
R  SMITH          RICHARD   PRODUCTION 10.00
1       9500.00A01
1       9050.00B01


Example: Creating a Structured HOLD File in FOCUS Format
TABLE FILE EMPLOYEE
PRINT LAST_NAME FIRST_NAME JOBCODE ED_HRS
BY DEPARTMENT
BY HIGHEST SALARY
ON TABLE SET EXTRACT ON
ON TABLE HOLD FORMAT FOCUS
END

This request produces the following HOLD Master File:

FILENAME=HOLD    , SUFFIX=FOC     , $
  SEGMENT=EMPINFO, SEGTYPE=S0, $
    FIELDNAME=LAST_NAME, ALIAS='LN', USAGE=A15, $
    FIELDNAME=FIRST_NAME, ALIAS='FN', USAGE=A10, $
    FIELDNAME=DEPARTMENT, ALIAS='DPT', USAGE=A10, $
    FIELDNAME=ED_HRS, ALIAS='OJT', USAGE=F6.2, $
  SEGMENT=PAYINFO, SEGTYPE=S0, PARENT=EMPINFO, $
    FIELDNAME=SALARY, ALIAS='SAL', USAGE=D12.2M, $
    FIELDNAME=JOBCODE, ALIAS='JBC', USAGE=A3, $


Example: Reconstituting a Structured HOLD File

The following request reconstitutes the original FOCUS data source from the Structured HOLD File created in Creating a Structured HOLD File in ALPHA Format:

TABLE FILE HOLD
PRINT LAST_NAME FIRST_NAME JOBCODE ED_HRS
BY DEPARTMENT
BY HIGHEST SALARY
ON TABLE SET EXTRACT ON
ON TABLE HOLD AS RECONST FORMAT FOCUS
END

This request produces the following Master File:

FILENAME=RECONST    , SUFFIX=FOC     , $
  SEGMENT=EMPINFO, SEGTYPE=S0, $
    FIELDNAME=LAST_NAME, ALIAS='LN', USAGE=A15, $
    FIELDNAME=FIRST_NAME, ALIAS='FN', USAGE=A10, $
    FIELDNAME=DEPARTMENT, ALIAS='DPT', USAGE=A10,
    FIELDNAME=ED_HRS, ALIAS='OJT', USAGE=F6.2, $
  SEGMENT=PAYINFO, SEGTYPE=S0, PARENT=EMPINFO, $
    FIELDNAME=SALARY, ALIAS='SAL', USAGE=D12.2M, $
    FIELDNAME=JOBCODE, ALIAS='JBC', USAGE=A3, $

The following request prints the report output:

TABLE FILE RECONST
PRINT LAST_NAME FIRST_NAME JOBCODE ED_HRS
BY DEPARTMENT
BY HIGHEST SALARY
END

The output is:

DEPARTMENT           SALARY  LAST_NAME        FIRST_NAME  JOBCODE  ED_HRS
----------           ------  ---------        ----------  -------  ------
MIS              $27,062.00  CROSS            BARBARA     A17       45.00
                 $25,775.00  CROSS            BARBARA     A16       45.00
                 $21,780.00  BLACKWOOD        ROSEMARIE   B04       75.00
                 $18,480.00  JONES            DIANE       B03       50.00
                             MCCOY            JOHN        B02         .00
                 $17,750.00  JONES            DIANE       B02       50.00
                 $13,200.00  SMITH            MARY        B14       36.00
                  $9,000.00  GREENSPAN        MARY        A07       25.00
                  $8,650.00  GREENSPAN        MARY        B01       25.00
PRODUCTION       $29,700.00  BANNING          JOHN        A17         .00
                 $26,862.00  IRVING           JOAN        A15       30.00
                 $24,420.00  IRVING           JOAN        A14       30.00
                 $21,120.00  ROMANS           ANTHONY     B04        5.00
                 $16,100.00  MCKNIGHT         ROGER       B02       50.00
                 $15,000.00  MCKNIGHT         ROGER       B02       50.00
                 $11,000.00  STEVENS          ALFRED      A07       25.00
                 $10,000.00  STEVENS          ALFRED      A07       25.00
                  $9,500.00  SMITH            RICHARD     A01       10.00
                  $9,050.00  SMITH            RICHARD     B01       10.00


Example: Excluding Fields From Structured HOLD Files

This request excludes the SALARY field used for sequencing.

TABLE FILE EMPLOYEE
PRINT LAST_NAME FIRST_NAME JOBCODE ED_HRS
BY DEPARTMENT
BY HIGHEST SALARY
ON TABLE SET EXTRACT *
EXCLUDE=(SALARY),$
ENDEXTRACT
ON TABLE HOLD FORMAT FOCUS
END

This request produces the following HOLD Master File:

FILENAME=HOLD   , SUFFIX=FOC     , $
  SEGMENT=EMPINFO, SEGTYPE=S0, $
    FIELDNAME=LAST_NAME, ALIAS='LN', USAGE=A15, $
    FIELDNAME=FIRST_NAME, ALIAS='FN', USAGE=A10, $
    FIELDNAME=DEPARTMENT, ALIAS='DPT', USAGE=A10, $
    FIELDNAME=ED_HRS, ALIAS='OJT', USAGE=F6.2, $
  SEGMENT=PAYINFO, SEGTYPE=S0, PARENT=EMPINFO, $
    FIELDNAME=JOBCODE, ALIAS='JBC', USAGE=A3, $

Top of page

x
Reference: Elements Included in a Structured HOLD File

Structured HOLD files contain all original segment instances required to complete the TABLE or TABLEF request. Regardless of the display command used in the original request (PRINT, LIST, SUM, or COUNT), the structured HOLD file will be created as if the command was PRINT.

Specifically, the extract file contains the following elements:


Top of page

x
Reference: Elements Not Included in a Structured HOLD File

Top of page

x
Reference: Structural and Behavioral Notes

Structural Notes

SQL Optimization Notes

BY/ACROSS/FOR Notes

Formatting Notes

DBA Notes

Reconstituting Extract Files


WebFOCUS