![[Compaq]](../../images/compaq.gif)
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
| Document revision date: 30 March 2001 | |
|
|
|
|
|
|
| Previous | Contents | Index |
The DCX$EXPAND_DONE routine deletes the context area and sets the context variable to zero.
DCX$EXPAND_DONE context
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.
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.
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).
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.
DCX$EXPAND_INIT context ,map
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.
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.
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.
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.
DCX$MAKE_MAP context ,map_addr [,map_size]
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.
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.
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.
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:
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:
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:
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:
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:
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:
For more information about how to link to the shareable image
TPUSHR.EXE, refer to the OpenVMS Programming Environment Manual.1
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:
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.
1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM. |
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:
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:
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.
| Previous | Next | Contents | Index |
|
|
| privacy and legal statement | ||
| 4493PRO_010.HTML | ||