Procedures under z/OS

ITEMS Procedure: z/OS

Builds, reads, and writes SAS item store files.

z/OS specifics:

all

Syntax
Details
	HTC File Format
	Alternate Syntax for the DIR= and ITEM= Options
PROC ITEMS Statement
LIST Statement
IMPORT Statement
EXPORT Statement
MERGE Statement
DELETE Statement
See Also

Syntax

PROC ITEMS NAME=<libref.>member;

Details

An item store is a SAS data set that consists of independently accessible chunks of information. SAS uses item store files for online Help, where the SAS help browser accesses an item store in the SASHELP library. You can use the ITEMS procedure to create, modify, and browse your own item store files, which you can then access through the SAS help browser.

The contents of an item store are divided into directories, subdirectories, and topics. The directory tree structure emulates the structure of UNIX System Services, so that a given Help topic is identified by a directory path (root_dir/sub_dir/item). This hierarchical structure allows the SAS help browser to support HTML links between Help topics.

The item store files that SAS uses for HTML help can be written only by users who have the appropriate privileges. Though SAS discourages rewrites of SAS help items, you can add items to the SAS help item store files, and you can develop new item store files of your own for any information that you want to make available through the SAS help browser. For further information about writing your own HTML help, see Using User-Defined Item Store Help Files.

To access an item store, you must first allocate the library that contains the item store, unless the item store is a member of the WORK library. After you allocate the library, you issue the PROC ITEMS NAME=fileref statement to access the item store in SAS. Once the item store is available in SAS, you can use the LIST, IMPORT, EXPORT, MERGE, and DELETE statements to control item store contents. SAS applies all of these statements to the item store name in the last PROC ITEMS NAME= statement.

For information about the HTML tags that are supported by the SAS help browser, see Creating User-Defined Item Store Help Files.

HTC File Format

Item store files are physically stored in the operating environment as HTC files. An HTC file is a text file that lists help filenames one per line, preceded by five colons, as follows:

:::::<filename>.htm

Directories in the HTC file are identified by a line that begins with five colons and ends with a path specification:

:::::<dirname1>/<dirname2>/<filename>.htm

HTC files can be imported and exported in HTC file format. Importing an HTC file with the IMPORT statement creates the necessary directories and subdirectories. For example, if an HTC file containing the preceding directory entry was imported into an item store with the IMPORT statement, the directory and subdirectory would be created as needed, and the file would be placed in the specified subdirectory. Any filename that lacks a path specification goes into the root directory or into the directory specified by the DIR= option, if it is specified in the IMPORT statement.

Alternate Syntax for the DIR= and ITEM= Options

You can use the forward slash path character (/) to specify a path in the DIR= and ITEM= options (described below) in all of the statements that take those options. For example, the following two statements are equivalent:

LIST DIR='usr' ITEM='mail';
LIST ITEM='usr/mail';

Note that a full path, starting with the directory just beneath the item store's root directory (with no initial forward slash) is required for access to anything except items in the root directory or to item store files consisting of a single item.

Wildcards, using asterisks (*) as in UNIX, are not accepted in item store paths. Nor can you specify more than one path (a file concatenation) for each of the following statements.

PROC ITEMS Statement

Syntax

PROC ITEMS NAME=<libref.>member;

The following argument is required in the PROC ITEMS statement:

NAME=: If no libref is specified, the libref is assumed to be WORK. If libref.member is specified, the libref must have been previously allocated. For more information about allocation, see LIBNAME Statement: z/OS.

LIST Statement

Syntax

LIST <options;>

The LIST statement writes a list of item names, a list of directory names, or both to the SAS log or to a specified file. Specifying no options writes a list of all items and directories to the SAS log.

The following options can be used in the LIST statement:

DUMP=fileref: specifies the fileref that receives the listing. If DUMP= is not specified, the output goes to the SAS log.
DIR='dir-name': specifies an item store directory whose item names you want to list. If you specify the DIR= option alone, you will receive a listing of item names contained in that directory.
ITEM='item-name': specifies that you want to list the contents of the named item in the named directory of the item store. If you specify an item without specifying a directory, you will receive the contents of the item with the specified name in the root directory of the item store.

IMPORT Statement

Syntax

IMPORT FILEREF=fileref <options>;

The IMPORT statement imports a fileref into an item store. If the imported fileref contains items or directories that currently exist in the item store, the new items or directories overwrite (replace) the existing versions.

The following options can be used in the IMPORT statement:

DIR='dir-name': specifies the item store directory that receives the imported fileref. If a directory is not specified, the fileref is imported into the root directory of the item store.
ITEM='item-name': specifies the name of the item that receives the imported fileref. If an item is not specified, the imported fileref is assumed to be an HTC file.

EXPORT Statement

Syntax

EXPORT FILEREF=fileref<options>;

The EXPORT statement copies an item or item store to an external fileref in HTC format. If the fileref exists before the EXPORT statement, the new fileref overwrites (replaces) the previous version.

The following options can be used in the EXPORT statement:

DIR='dir-name': specifies the item store directory that is the source of the export. If you do not specify a directory, the fileref receives the contents of the entire item store or the specified item from the root directory of the item store.
ITEM='item-name': specifies an item for export. If you do not specify an item, the fileref receives the entire contents of the specified directory or item store, in HTC format.

MERGE Statement

Syntax

MERGE SOURCE=<libref.>member;

The MERGE statement merges the specified item store into the item store opened previously with PROC ITEMS.

A libref is required in the MERGE statement. If the two item store files have directories with the same name and path, the contents of the new directory replace the contents of the old directory. If you merge into the root directory, the entire item store is replaced. If you merge a new item into a directory, the new item is merged into the old directory. If the old directory contains an item of the same name, the new item replaces the old item.

DELETE Statement

Syntax

DELETE <options>;

The DELETE statement deletes all or part of the contents in an item store.

The following options can be used in the DELETE statement:

DIR='dir-name': specifies the directory from which you want to delete. When DIR= is not specified, either the entire contents of the item store are deleted or the specified item is deleted from the item store's root directory.
ITEM='item-name': deletes the specified item from the specified directory in the item store, or if a directory is not specified, from the root directory of the item store.