Controlling Attributes in HOLD Master Files

Topics:

The commands SET ASNAMES, SET HOLDLIST, and SET HOLDATTR enable you to control the FIELDNAME, TITLE, and ACCEPT attributes in HOLD Master Files. These commands are issued prior to the report request and remain in effect for the duration of the session, unless you change them.

In addition, the SET HOLDSTAT command enables you to include comments and DBA information in the HOLD Master File. For more information about SET HOLDSTAT, see the Describing Data With WebFOCUS Language manual. For details about SET commands, see the Developing Reporting Applications manual.

Controlling Field Names in a HOLD Master File

How to:

Reference:

When SET ASNAMES is set to ON, MIXED or FOCUS, the literal specified in an AS phrase in a report request is used as the field name in a HOLD Master File. This command also controls how ACROSS fields are named in HOLD files.

Syntax: How to Control Field Names in a HOLD Master File

SET ASNAMES = [ON|OFF|MIXED|FOCUS|FLIP]

where:

OFF
Does not use the literal specified in an AS phrase as a field name in HOLD files, and does not affect the way ACROSS fields are named.
ON
Uppercases the literal specified in an AS phrase and propagates it as the field name in the HOLD Master File. Creates names for ACROSS fields that consist of the AS name value concatenated to the beginning of the ACROSS field value and controls the way ACROSS fields are named in HOLD files of any format.
MIXED
Uses the literal specified in an AS phrase for the field name, retaining the case of the AS name, and creates names for ACROSS fields that consist of the AS name value concatenated to the beginning of the ACROSS field value.
FOCUS
Uses the literal specified in an AS phrase as the field name and controls the way ACROSS fields are named only in HOLD files in FOCUS format. FOCUS is the default value.
FLIP

Propagates the field names in the original Master File to the alias names in the HOLD Master File and the alias names in the original Master File to the field names in the HOLD Master File.

Reference: Usage Notes for Controlling Field Names in HOLD Files

  • If no AS phrase is specified for a field, the field name from the original Master File is used. The TITLE attribute specified in the Master File is not used unless SET HOLDATTRS was previously issued.
  • To ensure that fields referenced more than once in a request have unique names in the HOLD Master File, use SET ASNAMES.
  • Special characters and blanks used in the AS phrase are preserved in the field name that is created when SET ASNAMES is used. Use single quotation marks around the non-standard field names when referring to them in the newly created Master File.
  • Text specified in an AS phrase that contains more than 66 characters is truncated to 66 characters in the Master File.
  • When generating field names and aliases for a HOLD file with the default setting for the ASNAMES parameter, if the HOLD file is a relational data source, the field names and aliases from the original Master File are propagated to the HOLD Master File. The alias names become the column names in the generated relational table. The AS name also becomes the TITLE attribute in the HOLD Master File.

    When you set the ASNAMES parameter to FLIP, for relational HOLD files, the field names from the original Master File or the AS names specified in the request become the alias names in the HOLD Master File as well as the column names in the generated relational table and the TITLE attributes in the HOLD Master File. The alias names in the original Master File become the field names in the HOLD Master File, except when there is an AS name, in which case the original field name becomes the HOLD field name.

  • If the HOLD file is not relational, field names from the original Master File are propagated to the HOLD Master File, but alias name are not propagated, and default aliases of the form E01, E02, and so on, are generated in the HOLD Master File.
  • For SET ASNAMES=FLIP, for non-relational HOLD files, the field names from the original Master File or the AS names from the request become the alias names in the HOLD Master File, and default field names are generated in the form F01, F02, and so on.
  • Duplicate field names may occur in the newly created Master File as a result of truncation or the way AS phrases have been specified. In this case, refer to the fields by their aliases (E01, E02, and so forth).
  • When commas are used as delimiters to break lines in the column heading, only the literal up to the first comma is used as the field name in the Master File. For example, the following produces the field name PLACE in the HOLD Master File:
    PRINT COUNTRY AS 'PLACE,OF,ORIGIN'
  • When ACROSS is used in a report request and the results are extracted to a HOLD file, the columns generated by the ACROSS phrase all have the same field name in the HOLD Master File. If SET ASNAMES is issued, each new column may have a unique field name. This unique field name consists of the ASNAME value specified in the request's display command, concatenated to the beginning of the value of the field used in the ACROSS phrase. If several field names have the same letters, this approach does not work.

    If an AS phrase is used for the fields in the ACROSS phrase, each new column has a field name composed of the literal in the AS phrase concatenated to the beginning of the value of the first field used in the ACROSS phrase.

Example: Controlling Field Names in the HOLD Master File

In the following example, SET ASNAMES=ON causes the text in the AS phrase to be used as field names in the HOLD1 Master File. The two fields in the HOLD1 Master File, NATION and AUTOMOBILE, contain the data for COUNTRY and CAR.

SET ASNAMES=ON
TABLE FILE CAR
PRINT CAR AS 'AUTOMOBILE'
BY COUNTRY AS 'NATION'
ON TABLE HOLD AS HOLD1
END

The request produces the following Master File:

FILE=HOLD1, SUFFIX=FIX
 SEGMENT=HOLD1, SEGTYPE=S01,$
  FIELDNAME=NATION      ,ALIAS=E01   ,USAGE=A10  ,ACTUAL=A12     ,$
  FIELDNAME=AUTOMOBILE  ,ALIAS=E02   ,USAGE=A16  ,ACTUAL=A16     ,$

Example: Providing Unique Field Names With SET ASNAMES

The following request generates a HOLD Master File with one unique field name for SALES and one for AVE.SALES. Both SALES and AVE.SALES would be named SALES, if SET ASNAMES had not been used.

SET ASNAMES=ON
TABLE FILE CAR
SUM SALES AND AVE.SALES AS 'AVERAGESALES'
BY CAR
ON TABLE HOLD AS HOLD2
END

The request produces the following Master File:

FILE=HOLD2, SUFFIX=FIX
 SEGMENT=HOLD2, SEGTYPE=S01,$
  FIELDNAME=CAR             ,ALIAS=E01  ,USAGE=A16 ,ACTUAL=A16   ,$
  FIELDNAME=SALES           ,ALIAS=E02  ,USAGE=I6  ,ACTUAL=I04   ,$
  FIELDNAME=AVERAGESALES    ,ALIAS=E03  ,USAGE=I6  ,ACTUAL=I04   ,$

Example: Using SET ASNAMES With the ACROSS Phrase

The following request produces a HOLD Master File with the literal CASH concatenated to each value of COUNTRY.

SET ASNAMES=ON
TABLE FILE CAR
SUM SALES AS 'CASH'
ACROSS COUNTRY
ON TABLE HOLD AS HOLD3
END

The request produces the following Master File:

FILE=HOLD3, SUFFIX=FIX
 SEGMENT=HOLD3, SEGTYPE=S01,$
  FIELDNAME=CASHENGLAND     ,ALIAS=E01   ,USAGE=I6  ,ACTUAL=I04  ,$
  FIELDNAME=CASHFRANCE      ,ALIAS=E02   ,USAGE=I6  ,ACTUAL=I04  ,$
  FIELDNAME=CASHITALY       ,ALIAS=E03   ,USAGE=I6  ,ACTUAL=I04  ,$
  FIELDNAME=CASHJAPAN       ,ALIAS=E04   ,USAGE=I6  ,ACTUAL=I04  ,$
  FIELDNAME=CASHW GERMANY   ,ALIAS=E05   ,USAGE=I6  ,ACTUAL=I04  ,$

Without the SET ASNAMES command, every field in the HOLD FILE is named COUNTRY.

To generate field names for ACROSS values that include only the field value, use the AS phrase followed by two single quotation marks, as follows:

SET ASNAMES=ON
TABLE FILE CAR
SUM SALES AS ''
ACROSS COUNTRY
ON TABLE HOLD AS HOLD4
END

The resulting Master File looks like this:

FILE=HOLD4, SUFFIX=FIX
 SEGMENT=HOLD4, SEGTYPE=S0,$
  FIELDNAME=ENGLAND    ,ALIAS=E01   ,USAGE=I6  ,ACTUAL=I04    ,$
  FIELDNAME=FRANCE     ,ALIAS=E02   ,USAGE=I6  ,ACTUALI04     ,$
  FIELDNAME=ITALY      ,ALIAS=E03   ,USAGE=I6  ,ACTUALI04     ,$
  FIELDNAME=JAPAN      ,ALIAS=E04   ,USAGE=I6  ,ACTUALI04     ,$
  FIELDNAME=W GERMANY  ,ALIAS=E05   ,USAGE=I6  ,ACTUALI04     ,$

Example: Generating a HOLD File With SET ASNAMES=FLIP

The following request generates a HOLD file in ALPHA format using the OFF value for SET ASNAMES. The field CURR_SAL has the AS name SALARY in the request:

SET ASNAMES=OFF
TABLE FILE EMPLOYEE
SUM CURR_SAL AS SALARY PCT_INC
BY DEPARTMENT
ON TABLE HOLD FORMAT ALPHA
END

In the HOLD Master File, AS names have not been propagated, the field names are from the original Master File, and default alias names are generated:

FILENAME=HOLD    , SUFFIX=FIX     , IOTYPE=STREAM, $
  SEGMENT=HOLD, SEGTYPE=S1, $
    FIELDNAME=DEPARTMENT, ALIAS=E01, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=CURR_SAL, ALIAS=E02, USAGE=D12.2M, ACTUAL=A12, $
    FIELDNAME=PCT_INC, ALIAS=E03, USAGE=F6.2, ACTUAL=A06, $

The following version of the request generates a relational table:

SET ASNAMES=OFF
TABLE FILE EMPLOYEE
SUM CURR_SAL AS SALARY PCT_INC
BY DEPARTMENT
ON TABLE HOLD FORMAT SQLMSS
END

The field names from the original Master File have been propagated to the field names in the HOLD Maser File, and the alias names from the original Master File have been propagated to the HOLD Master File. The AS name for CURR_SAL has become the TITLE in the HOLD Master File:

FILENAME=HOLD   , SUFFIX=SQLMSS  , $
  SEGMENT=SEG01, SEGTYPE=S0, $
    FIELDNAME=DEPARTMENT, ALIAS=DPT, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=CURR_SAL, ALIAS=CSAL, USAGE=D12.2M, ACTUAL=D8,
      TITLE='SALARY', $
    FIELDNAME=PCT_INC, ALIAS=PI, USAGE=F6.2, ACTUAL=F4, $

Changing SET ASNAMES to ON propagates the AS name SALARY to the field name in the HOLD Master File. The following is the Master File for the HOLD file in ALPHA format:

FILENAME=HOLD    , SUFFIX=FIX     , IOTYPE=STREAM, $
  SEGMENT=HOLD, SEGTYPE=S1, $
    FIELDNAME=DEPARTMENT, ALIAS=E01, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=SALARY, ALIAS=E02, USAGE=D12.2M, ACTUAL=A12, $
    FIELDNAME=PCT_INC, ALIAS=E03, USAGE=F6.2, ACTUAL=A06, $

The following is the Master File for the HOLD file in relational format:

FILENAME=HOLD   , SUFFIX=SQLMSS  , $
  SEGMENT=SEG01, SEGTYPE=S0, $
    FIELDNAME=DEPARTMENT, ALIAS=DPT, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=SALARY, ALIAS=CURR_SAL, USAGE=D12.2M, ACTUAL=D8,
      TITLE='SALARY', $
    FIELDNAME=PCT_INC, ALIAS=PI, USAGE=F6.2, ACTUAL=F4, $

Changing SET ASNAMES to FLIP propagates the AS name SALARY to the alias name in the HOLD Master File. In the ALPHA HOLD file, the other field names have been propagated to the alias names in the HOLD Master File, and default field names have been generated:

FILENAME=HOLD    , SUFFIX=FIX     , IOTYPE=STREAM, $
  SEGMENT=HOLD, SEGTYPE=S1, $
    FIELDNAME=F01, ALIAS=DEPARTMENT, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=F02, ALIAS=SALARY, USAGE=D12.2M, ACTUAL=A12, $
    FIELDNAME=F03, ALIAS=PCT_INC, USAGE=F6.2, ACTUAL=A06, $

In the relational HOLD file, changing SET ASNAMES to FLIP propagates the AS name SALARY to the alias name in the HOLD Master File. For that field, the field name from the original Master File becomes the field name in the HOLD Master File and the TITLE attribute. The other field names have been propagated to the alias names in the HOLD Master File, and the corresponding alias names from the original Master File have been propagated to the field names in the HOLD Master File:

FILENAME=HOLD   , SUFFIX=SQLMSS  , $
  SEGMENT=SEG01, SEGTYPE=S0, $
    FIELDNAME=DPT, ALIAS=DEPARTMENT, USAGE=A10, ACTUAL=A10, $
    FIELDNAME=CURR_SAL, ALIAS=SALARY, USAGE=D12.2M, ACTUAL=D8,
      TITLE='SALARY', $
    FIELDNAME=PI, ALIAS=PCT_INC, USAGE=F6.2, ACTUAL=F4, $

Controlling Fields in a HOLD Master File

How to:

You can use the SET HOLDLIST command to restrict fields in HOLD Master Files to those appearing in a request.

Syntax: How to Control Fields in a HOLD File

SET HOLDLIST = {PRINTONLY|ALL|ALLKEYS|EXPLICIT}

where:

PRINTONLY
Specifies that only those fields that would appear in the report are included in the generated HOLD file. Non-displaying fields in a request (those designated as NOPRINT fields explicitly or implicitly) are not included in the HOLD file.
ALL
Specifies that all display fields referenced in a request appear in a HOLD file, including calculated values. ALL is the default value. OLD may be used as a synonym for ALL.

Note: Vertical sort (BY) fields specified in the request with the NOPRINT option are not included in the HOLD file even if HOLDLIST=ALL.

ALLKEYS
Propagates all fields, including NOPRINTed BY fields.

The ALLKEYS setting enables caching of all of the data necessary for manipulating an active report.

EXPLICIT
Includes fields in the HOLD or PCHOLD file that are explicitly omitted from the report output using the NOPRINT option in the request, but does not include fields that are implicitly NOPRINTed. For example, if a field is reformatted in the request, two versions of the field exist, the one with the new format and the one with the original format, which is implicitly NOPRINTed

Note that SET HOLDLIST may also be issued from within a TABLE request. When used with MATCH, SET HOLDLIST always behaves as if HOLDLIST is set to ALL.

Example: Using HOLDLIST=ALL

When HOLDLIST is set to ALL, the following TABLE request produces a HOLD file containing all specified fields, including NOPRINT fields and values calculated with the COMPUTE command.

SET HOLDLIST=ALL
 
TABLE FILE CAR
PRINT CAR MODEL NOPRINT
COMPUTE TEMPSEATS=SEATS+1;
BY COUNTRY
ON TABLE HOLD
END
 
? HOLD

The output is:

NUMBER OF RECORDS IN TABLE=     18
LINE=          
18
DEFINITION OF HOLD FILE: HOLD
FIELDNAME
ALIAS
FORMAT
 
COUNTRY
E01
A10
CAR
E02
A16
MODEL
E03
A24
SEATS
E04
I3
TEMPSEATS
E05
D12.2

 

Example: Using HOLDLIST= PRINTONLY

When HOLDLIST is set to PRINTONLY, the following TABLE request produces a HOLD file containing only fields that would appear in report output:

SET HOLDLIST=PRINTONLY
 
TABLE FILE CAR
PRINT CAR MODEL NOPRINT
COMPUTE TEMPSEATS=SEATS+1;
BY COUNTRY
ON TABLE HOLD
END
 
? HOLD

The output is:

NUMBER OF RECORDS IN TABLE=    18    
LINES=     
18
DEFINITION OF HOLD FILE: HOLD
FIELDNAME
ALIAS
FORMAT
 
COUNTRY
E01
A10
CAR
E02
A16
TEMPSEATS
E03
D12.2

Example: Comparing Master Files Created Using Different HOLDLIST Settings

The following request against the GGSALES data source has two reformatted display fields (DOLLARS, UNITS). The DOLLARS field is also an explicit NOPRINT field. The BY field named CATEGORY is also an explicit NOPRINT field:

SET HOLDLIST=ALL
TABLE FILE GGSALES
SUM UNITS/I5 DOLLARS/D12.2 NOPRINT
BY REGION BY CATEGORY NOPRINT
ON TABLE HOLD FORMAT FOCUS
END

Running the request with SET HOLDLIST=ALL generates the following HOLD Master File. Note that the DOLLARS and UNITS fields are included twice, once with the original format (which would have been implicitly NOPRINTed if the report had been printed rather than held) and once with the new format. However the NOPRINTed BY field (CATEGORY) is not included:

FILENAME=HOLD, SUFFIX=FOC     , $
  SEGMENT=SEG01, SEGTYPE=S1, $
    FIELDNAME=REGION, ALIAS=E01, USAGE=A11,
      TITLE='Region', DESCRIPTION='Region code', $
    FIELDNAME=UNITS, ALIAS=E02, USAGE=I08,
      TITLE='Unit Sales', DESCRIPTION='Number of units sold', $
    FIELDNAME=UNITS, ALIAS=E03, USAGE=I5,
      TITLE='Unit Sales', $
    FIELDNAME=DOLLARS, ALIAS=E04, USAGE=I08,
      TITLE='Dollar Sales', DESCRIPTION='Total dollar amount of reported sales', $
    FIELDNAME=DOLLARS, ALIAS=E05, USAGE=D12.2,
      TITLE='Dollar Sales', $

Running the request with SET HOLDLIST=ALLKEYS generates the following HOLD Master File. Note that the DOLLARS and UNITS fields are included twice, once with the original format, which would have been implicitly NOPRINTed if the report had been printed rather than held, and once with the new format. The NOPRINTed BY field (CATEGORY) is included:

FILENAME=HOLD, SUFFIX=FOC     , $
  SEGMENT=SEG01, SEGTYPE=S2, $
    FIELDNAME=REGION, ALIAS=E01, USAGE=A11,
      TITLE='Region', DESCRIPTION='Region code', $
    FIELDNAME=CATEGORY, ALIAS=E02, USAGE=A11,
      TITLE='Category', DESCRIPTION='Product category', $
    FIELDNAME=UNITS, ALIAS=E03, USAGE=I08,
      TITLE='Unit Sales', DESCRIPTION='Number of units sold', $
    FIELDNAME=UNITS, ALIAS=E04, USAGE=I5,
      TITLE='Unit Sales', $
    FIELDNAME=DOLLARS, ALIAS=E05, USAGE=I08,
      TITLE='Dollar Sales', DESCRIPTION='Total dollar amount of reported sales', $
    FIELDNAME=DOLLARS, ALIAS=E06, USAGE=D12.2,
      TITLE='Dollar Sales', $

Running the request with SET HOLDLIST=PRINTONLY generates the following HOLD Master File. Only the fields that would have actually printed on the report output are included: REGION and UNITS with the new format (I5). All explicitly and implicitly NOPRINTed fields are excluded, including the NOPRINTed BY field (CATEGORY):

FILENAME=HOLD , SUFFIX=FOC     , $
  SEGMENT=SEG01, SEGTYPE=S1, $
    FIELDNAME=REGION, ALIAS=E01, USAGE=A11,
      TITLE='Region', DESCRIPTION='Region code', $
    FIELDNAME=UNITS, ALIAS=E02, USAGE=I5,
      TITLE='Unit Sales', $

Running the request with SET HOLDLIST=EXPLICIT generates the following HOLD Master File. The fields that would have actually printed on the report output are included and so are the explicitly NOPRINTed fields (the display field DOLLARS and the BY field CATEGORY). The implicitly NOPRINTed fields (DOLLARS and UNITS with their original formats) are omitted:

FILENAME=HOLD, SUFFIX=FOC     , $
  SEGMENT=SEG01, SEGTYPE=S2, $
    FIELDNAME=REGION, ALIAS=E01, USAGE=A11,
      TITLE='Region', DESCRIPTION='Region code', $
    FIELDNAME=CATEGORY, ALIAS=E02, USAGE=A11,
      TITLE='Category', DESCRIPTION='Product category', $
    FIELDNAME=UNITS, ALIAS=E03, USAGE=I5,
      TITLE='Unit Sales', $
    FIELDNAME=DOLLARS, ALIAS=E04, USAGE=D12.2,
      TITLE='Dollar Sales', $

Controlling the TITLE and ACCEPT Attributes in the HOLD Master File

How to:

The SET HOLDATTR command controls whether the TITLE and ACCEPT attributes in the original Master File are propagated to the HOLD Master File. SET HOLDATTR does not affect the way fields are named in the HOLD Master File.

Note that if a field in a data source does not have the TITLE attribute specified in the Master File, but there is an AS phrase specified for the field in a report request, the corresponding field in the HOLD file is named according to the AS phrase.

Syntax: How to Control TITLE and ACCEPT Attributes

SET HOLDATTR =[ON|OFF|FOCUS]

where:

ON
Uses the TITLE attribute as specified in the original Master File in HOLD files in any format. The ACCEPT attribute is propagated to the HOLD Master File only for HOLD files in FOCUS format.
OFF
Does not use the TITLE or ACCEPT attributes from the original Master File in the HOLD Master File.
FOCUS
Uses the TITLE and ACCEPT attributes only for HOLD files in FOCUS format. FOCUS is the default value.

Example: Controlling TITLE and ACCEPT Attributes in a HOLD Master File

In this example, the Master File for the CAR data source specifies TITLE and ACCEPT attributes:

FILENAME=CAR2, SUFFIX=FOC
SEGNAME=ORIGIN, SEGTYPE=S1
  FIELDNAME =COUNTRY, COUNTRY, A10, TITLE='COUNTRY OF ORIGIN',
             ACCEPT='CANADA' OR 'ENGLAND' OR 'FRANCE' OR 'ITALY' OR
                    'JAPAN' OR 'W GERMANY',
             FIELDTYPE=I,$
SEGNAME=COMP, SEGTYPE=S1, PARENT=ORIGIN
  FIELDNAME=CAR, CARS, A16, TITLE='NAME OF CAR',$
.
.
.

Using SET HOLDATTR=FOCUS, the following request

SET HOLDATTR = FOCUS
TABLE FILE CAR2
PRINT CAR
BY COUNTRY ON TABLE HOLD FORMAT FOCUS AS HOLD5
END

produces this HOLD Master File:

FILE=HOLD5, SUFFIX=FOC
 SEGMENT=SEG01, SEGTYPE=S02
  FIELDNAME=COUNTRY ,USAGE=E01   ,ACTUAL=A10
      TITLE='COUNTRY OF ORIGIN',
      ACCEPT=CANADA ENGLAND FRANCE ITALY JAPAN 'W GERMANY',$
  FIELDNAME=FOCLIST ,USAGE=E02   ,ACTUAL=I5     ,$
  FIELDNAME=CAR     ,USAGE=E03   ,ACTUAL=A16    ,
      TITLE='NAME OF CAR' ,$

WebFOCUS

Feedback