Using the vosview utility

Purpose

The vosview program displays the data in the PKI Services object store (the request database). Depending on how you have configured PKI Services, the object store can be in a VSAM data set or in a DB2® table. Each request record consists of a fixed header, followed by a variable-length section. For each entry vosview displays the header information and optionally calls a user-provided program to process the BER-encoded request.

Path setup

Update your PATH, LIBPATH, and NLSPATH environment variables with the appropriate pkiserv directory before you run vosview. (Note that you are updating the environment variables for the user running the utility, not updating values in the PKI Services environment variables file, pkiserv.envars.) Once you have updated these variables, you can run vosview from the UNIX command line.

Variable name	You must add …
PATH	`/install-dir/pkiserv/bin`
LIBPATH	`/install-dir/pkiserv/lib`
NLSPATH	`/install-dir/pkiserv/lib/nls/msg/%L/%N`

The default directory for install-dir is /usr/lpp.

Format

vosview {-d vsam-dataset-name [-r] | -b db2-subsystem-name -k db2-package-name 
        | -c [-p path]}
        [-D CA-domain-name] [-s decode-command-string]

Parameters

You can display usage information about the vosview command format and parameters when you issue the vosview utility command with no parameters.

-d vsam-dataset-name

Specifies the MVS™ data set name of the VSAM object store.

If you specify -d, do not specify -b, -k or -c. If you do, the utility issues an error message and the command fails.

Note: If the data set name has no quotes, the program uses the invoker of the command as the first qualifier. If you specify the fully qualified data set name, use quotes, and make sure to include the escape character, which is a backslash (\), before the quotation marks enclosing the data set name. For example, see \'pkisrvd.vsam.ost\' in Examples.

-r

Indicates to open in record-level sharing (RLS) mode the VSAM data set specified with the -d option.

-r is ignored and the utility issues a warning message if -b and -k are specified, or if -c is specified.

-b db2-subsystem-name

Specifies the name of the DB2 subsystem or group attachment where the object store is located.

If you specify -b and you do not specify -k, or you specify -d or -c, the utility issues an error message and the command fails.

-k db2-package-name

Specifies the DB2 package name of the object store.

If you specify -k and do not specify -b, or you specify -d or -c, the utility issues an error message and the command fails.

-c

Indicates to retrieve the location of the object store from the pkiserv.conf configuration file. Either the VSAM data set name is retrieved, or the DB2 subsystem name and package name are retrieved, depending which you are using. For VSAM, the SharedPlex value determines whether the VSAM data set is opened in record-level sharing (RLS) mode. (For DB2, the SharedPlex value has no effect on this utility.)

If you specify -c, and you also specify -d, -b, or -k, the utility issues an error message and the command fails.

Note: When you also specify the -D option, you must use the -p option to specify the CA domain configuration directory if it is not /etc/pkiserv.

-p path

Specifies the directory where the pkiserv.conf configuration file resides. If not specified, the directory defaults to /etc/pkiserv. This option is only valid when specified with the -c option. If specified with the -b, -k, or -d options, the utility issues a warning message, and the -p option is ignored.

-D CA-domain-name

Specifies the CA domain name where this utility command is directed.

Notes:

The -D option is required only if PKI Services is running in multiple-CA mode.
The CA-domain-name value can be entered using uppercase or lowercase letters.
When you also specify the -c option, you must use the -p option to specify the CA domain configuration directory if not /etc/pkiserv.

-s decode-command-string

Specifies an optional command to call for decoding the ASN.1-encoded data. (The command must be able to read and decode binary (BER) data from STDIN.)

Examples

To view the records in the VSAM object store data set 'PKISRVD.VSAM.OST', passing the request data to a utility called dumpasn1, use the following command:

vosview -d \'pkisrvd.vsam.ost\' -s 'dumpasn1 -'

To view the records in the object store for the CA domain MasterCA using the information from the pkiserv.conf file located in the directory /etc/pkiserv/MasterCA, use the following command:

vosview -c -p /etc/pkiserv/MasterCA -D MasterCA

To view the records in the object store in the DB2 subsystem DSN9 with a package name of MasterCA, passing the request data to a utility called dumpasn1, and redirecting the output to the file vos.out, use the following command:

vosview -b DSN9 -k MASTERCA -s 'dumpasn1 -' >vos.out

Note: A dumpasn1 utility is not shipped with PKI Services.

Output

Records with an object key value of 100 or higher display common information stored for each record. Records with an object key value less than 100 are special records maintained by the PKI Services daemon and the information displayed is specific to the record.