HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

The DCX$EXPAND_DONE routine deletes the context area and sets the context variable to zero.

Format

DCX$EXPAND_DONE context

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Value identifying the data stream that DCX$EXPAND_DONE deletes. The context argument is the address of a longword containing this value. DCX$EXPAND_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

Description

The DCX$EXPAND_DONE routine deletes the context area and sets the context variable to zero, thus undoing the work of the DCX$EXPAND_INIT routine. Call DCX$EXPAND_DONE when all data records have been expanded (using DCX$EXPAND_DATA).

Condition Values Returned

DCX$_INVCTX	Error. The context variable is invalid, or the context area is invalid or corrupted. This may be caused by a failure to call the appropriate routine to initialize the context variable or by an application program error.
DCX$NORMAL	Normal successful completion.

This routine also returns any condition values returned by LIB$FREE_VM.

The DCX$EXPAND_INIT routine initializes the context area for the expansion of data records.

Format

DCX$EXPAND_INIT context ,map

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Value identifying the data stream that DCX$EXPAND_INIT initializes. The context argument is the address of a longword containing this value. After DCX$EXPAND_INIT initializes this context value, you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

map

OpenVMS usage:	address
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Compression/expansion function (created by DCX$MAKE_MAP). The map argument is the address of the compression/expansion function's virtual address.

The map argument must remain at this address until data expansion is completed and context is deleted by means of a call to DCX$EXPAND_DONE.

Description

The DCX$EXPAND_INIT routine initializes the context area for the expansion of data records.

Call the DCX$EXPAND_INIT routine as the first step in the expansion (or restoration) of compressed data records to their original state.

Before you call DCX$EXPAND_INIT, read the length of the compressed file from the compression/expansion function (the map). Invoke LIB$GET_VM to get the necessary amount of storage for the function. LIB$GET_VM returns the address of the first byte of the storage area.

Condition Values Returned

DCX$_INVMAP	Error; invalid map. The map argument was not specified correctly, or the context area is invalid.
DCX$_NORMAL	Normal successful completion.

This routine also returns any condition values returned by LIB$GET_VM.

The DCX$MAKE_MAP routine uses the statistical information gathered by DCX$ANALYZE_DATA to compute the compression/expansion function.

Format

DCX$MAKE_MAP context ,map_addr [,map_size]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Value identifying the data stream that DCX$MAKE_MAP maps. The context argument is the address of a longword containing this value. DCX$ANALYZE_INIT initializes this value; you should not modify it. You can define multiple context arguments to identify multiple data streams that are processed simultaneously.

map_addr

OpenVMS usage:	address
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Starting address of the compression/expansion function. The map_addr argument is the address of a longword into which DCX$MAKE_MAP stores the virtual address of the compression/expansion function.

map_size

OpenVMS usage:	longword_signed
type:	longword (unsigned)
access:	write only
mechanism:	by reference

Length of the compression/expansion function. The map_size argument is the address of the longword into which DCX$MAKE_MAP writes the length of the compression/expansion function.

Description

The DCX$MAKE_MAP routine uses the statistical information gathered by DCX$ANALYZE_DATA to compute the compression/expansion function. In essence, this map is the algorithm used to shorten (or compress) the original data records as well as to expand the compressed records to their original form.

The map must be available in memory when any data compression or expansion takes place; the address of the map is passed as an argument to the DCX$COMPRESS_INIT and DCX$EXPAND_INIT routines, which initialize the data compression and expansion procedures, respectively.

The map is stored with the compressed data records, because the compressed data records are indecipherable without the map. When compressed data records have been expanded to their original state and no further compression is desired, you should delete the map using the LIB$FREE_VM routine.

DCX requires that you submit data records for analysis and then call the DCX$MAKE_MAP routine. Upon receiving the DCX$_AGAIN status code, you must again submit data records for analysis (in the same order) and call DCX$MAKE_MAP again; on the second iteration, DCX$MAKE_MAP returns the DCX$_NORMAL status code.

Condition Values Returned

DCX$_AGAIN	Informational. The map has not been created and the map_addr and map_size arguments have not been written because further analysis is required. The data records must be analyzed (using DCX$ANALYZE_DATA) again, and DCX$MAKE_MAP must be called again before DCX$MAKE_MAP will create the map and return the DCX$_NORMAL status code.
DCX$_INVCTX	Error. The context variable is invalid, or the context area is invalid or corrupted. This may be caused by a failure to call the appropriate routine to initialize the context variable or by an application program error.
DCX$_NORMAL	Normal successful completion.

This routine also returns any condition values returned by LIB$GET_VM and LIB$FREE_VM.

This chapter describes callable DEC Text Processing Utility (DECTPU) routines. It describes the purpose of the DECTPU callable routines, the parameters for the routine call, and the primary status returns. The parameter in the call syntax represents the object that you pass to a DECTPU routine. Each parameter description lists the data type and the passing mechanism for the object. The data types are standard OpenVMS data types. The passing mechanism indicates how the parameter list is interpreted.

This chapter is written for system programmers who are familiar with the:

• OpenVMS Calling Standard
• OpenVMS Run-Time Library
• Precise manner in which data types are represented on a VAX processor or an Alpha processor
• Method for calling routines written in a language other than the one you are using for the main program

Callable DECTPU routines make DECTPU accessible from within other languages and applications supported by OpenVMS. DECTPU can be called from a program written in any language that generates calls using the OpenVMS Calling Standard. You can also call DECTPU from OpenVMS utilities, for example, the Mail utility. Callable DECTPU lets you perform text-processing functions within your program.

Callable DECTPU consists of a set of callable routines that resides in the DECTPU shareable images. You access callable DECTPU by linking against the shareable images, which include the callable interface routine names and constants. As with the DCL-level DECTPU interface, you can use files for input to and output from callable DECTPU. You can also write your own routines for processing file input, output, and messages.

The calling program must ensure that parameters passed to a called procedure, in this case DECTPU, are of the type and form that the DECTPU procedure accepts.

The DECTPU routines described in this chapter return condition values indicating the routine's completion status. When comparing a returned condition value with a test value, you should use the LIB$MATCH routine from the Run-Time Library. Do not test the condition value as if it were a simple integer.

8.1.1 Interfaces to Callable DECTPU

There are two interfaces you can use to access callable DECTPU: the simplified callable interface and the full callable interface.

8.1.1.1 Simplified Callable Interface

The easiest way to use callable DECTPU is to use the simplified callable interface. DECTPU provides two alternative routines in its simplified callable interface. These routines in turn call additional routines that do the following:

• Initialize the editor
• Provide the editor with the parameters necessary for its operation
• Control the editing session
• Perform error handling

When using the simplified callable interface, you can use the TPU$TPU routine to specify a command line for DECTPU, or you can call the TPU$EDIT routine to specify an input file and an output file. TPU$EDIT builds a command string that is then passed to the TPU$TPU routine. These two routines are described in detail in Section 8.2.

If your application parses information that is not related to the operation of DECTPU, make sure the application obtains and uses all non-DECTPU parse information before the application calls the simplified callable interface. You must do this because the simplified callable interface destroys all parse information obtained and stored before the simplified callable interface was called.

8.1.1.2 Full Callable Interface

To use the full callable interface, have your program access the main callable DECTPU routines directly. These routines do the following:

• Initialize the editor (TPU$INTIALIZE)
• Execute DECTPU procedures (TPU$EXECUTE_INIFILE and TPU$EXECUTE_COMMAND)
• Give control to the editor (TPU$CONTROL)
• Terminate the editing session (TPU$CLEANUP)

When using the full callable interface, you must provide values for certain parameters. In some cases, the values you supply are actually addresses for additional routines. For example, when you call TPU$INITIALIZE, you must include the address of a routine that specifies initialization options. Depending on your particular application, you might also have to write additional routines. For example, you might need to write routines for performing file operations, handling errors, and otherwise controlling the editing session. Callable DECTPU provides utility routines that can perform some of these tasks for you. These utility routines can do the following:

• Parse the command line and build the item list used for initializing the editor
• Handle file operations
• Output error messages
• Handle conditions

If your application calls the DECwindows version of DECTPU, the application can call TPU$INITIALIZE only once.

Various topics relating to the full callable interface are discussed in the following sections:

• Section 8.3 begins by briefly describing the interface. However, most of this section describes the main callable DECTPU routines (TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, TPU$EXECUTE_COMMAND, and TPU$CLEANUP).
• Section 8.3.2 discusses additional routines that DECTPU provides for use with the full callable interface.
• Section 8.3.3 defines the requirements for routines that you can write for use with the full callable interface.

The full callable interface consists of the main callable DECTPU routines and the DECTPU utility routines.

8.1.2 The DECTPU Shareable Image

Whether you use the simplified callable interface or the full callable interface, you access callable DECTPU by linking against the DECTPU shareable image. This image contains the routine names and constants available for use by an application. In addition, the shareable image provides the following symbols:

• TPU$GL_VERSION---The version of the shareable image
• TPU$GL_UPDATE---The update number of the shareable image
• TPU$_FACILITY---The DECTPU facility code

For more information about how to link to the shareable image TPUSHR.EXE, refer to the OpenVMS Programming Environment Manual.¹

8.1.3 Passing Parameters to Callable DECTPU Routines

Parameters are passed to callable DECTPU routines by reference or by descriptor. When the parameter is a routine, the parameter is passed by descriptor as a bound procedure value (BPV) data type.

A bound procedure value is a two-longword entity in which the first longword contains a procedure value and the second longword is the environment value (see the following figure). The environment value is determined in a language-specific manner when the original bound procedure value is generated. When the bound procedure is called, the calling program loads the second longword into R1.

When you use the simplified callable interface, DECTPU establishes its own condition handler, TPU$HANDLER, to handle all errors. When you use the full callable interface, there are two ways to handle errors:

• You can use the DECTPU default condition handler, TPU$HANDLER.
• You can write your own condition handler to process some of the errors and call TPU$HANDLER to process the rest.

The default condition handler, TPU$HANDLER, is described in Section 8.7. Information about writing your own condition handler can be found in the OpenVMS Programming Concepts Manual.

8.1.5 Return Values

All DECTPU condition codes are declared as universal symbols. Therefore, you automatically have access to these symbols when you link your program to the shareable image. The condition code values are returned in R0. Return codes for DECTPU can be found in the DEC Text Processing Utility Reference Manual. DECTPU return codes and their messages are accessible from the Help/Message facility.

Additional information about condition codes is provided in the descriptions of callable DECTPU routines found in subsequent sections. This information is provided under the heading Condition Values Returned and indicates the values that are returned when the default condition handler is established.

8.2 Simplified Callable Interface

The DECTPU simplified callable interface consists of two routines: TPU$TPU and TPU$EDIT. These entry points to DECTPU are useful for the following kinds of applications:

• Those able to specify all the editing parameters on a single command line
• Those that need to specify only an input file and an output file

If your application parses information that is not related to the operation of DECTPU, make sure the application obtains and uses all non-DECTPU parse information before the application calls the simplified callable interface. You must do this because the simplified callable interface destroys all parse information obtained and stored before the simplified callable interface was called.

The following example calls TPU$EDIT to edit text in the file INFILE.DAT and writes the result to OUTFILE.DAT. Note that the parameters to TPU$EDIT must be passed by descriptor.

/*
  Sample C program that calls DECTPU.  This program uses TPU$EDIT to
  provide the names of the input and output files
*/

#include descrip

int return_status;

static $DESCRIPTOR (input_file, "infile.dat");
static $DESCRIPTOR (output_file, "outfile.dat");

main (argc, argv)
    int argc;
    char *argv[];

    {
    /*
      Call DECTPU to edit text in "infile.dat" and write the result
      to "outfile.dat".  Return the condition code from DECTPU as the
      status of this program.
    */

    return_status = TPU$EDIT (&input_file, &output_file);
    exit (return_status);
    }

The next example performs the same task as the previous example. This time, the TPU$TPU entry point is used. TPU$TPU accepts a single argument which is a command string starting with the verb TPU. The command string can contain all of the qualifiers that are accepted by the EDIT/TPU command.

/*
  Sample C program that calls DECTPU.  This program uses TPU$TPU and
  specifies a command string
*/

#include descrip

int return_status;

static $DESCRIPTOR (command_prefix, "TPU/NOJOURNAL/NOCOMMAND/OUTPUT=");
static $DESCRIPTOR (input_file, "infile.dat");
static $DESCRIPTOR (output_file, "outfile.dat");
static $DESCRIPTOR (space_desc, " ");

char command_line [100];
static $DESCRIPTOR (command_desc, command_line);

main (argc, argv)
    int argc;
    char *argv[];

    {
    /*
      Build the command line for DECTPU.  Note that the command verb
      is TPU instead of EDIT/TPU.  The string we construct in the
      buffer command_line will be
        "TPU/NOJOURNAL/NOCOMMAND/OUTPUT=outfile.dat infile.dat"
    */

    return_status = STR$CONCAT (&command_desc,
                                &command_prefix,
                                &output_file,
                                &space_desc,
                                &input_file);
    if (! return_status)
        exit (return_status);

    /*
      Now call DECTPU to edit the file
    */
    return_status = TPU$TPU (&command_desc);
    exit (return_status);
    }

The following section contains detailed information about the routines in the full DECTPU callable interface. If you use the simplified interface, that interface calls these routines for you. If you use the full interface, your code calls these routines directly.

8.3 Full Callable Interface

The DECTPU full callable interface consists of a set of routines that you can use to perform the following tasks:

• Specify initialization parameters
• Control file input/output
• Specify commands to be executed by the editor
• Control how conditions are handled

When you use the simplified callable interface, these operations are performed automatically. The individual DECTPU routines that perform these functions can be called from a user-written program and are known as the DECTPU full callable interface. This interface has two sets of routines: the main DECTPU callable routines and the DECTPU utility routines. These DECTPU routines, as well as your own routines that pass parameters to the DECTPU routines, are the mechanism that your application uses to control DECTPU.

The following sections describe the main callable routines, how parameters are passed to these routines, the DECTPU utility routines, and the requirements of user-written routines.