C/C++ Programmer's Guide (G06.27+, H06.08+, J06.03+)

3 Interfacing to Guardian Procedures and OSS Functions
This chapter describes how to declare and call Guardian procedures and OSS functions in C and
C++ programs.
Use Guardian procedures when you cannot accomplish a task with C functions. For example, to
get the file code of a Guardian file, use a Guardian file-system procedure, such as FILE_GETINFO_
or FILE_GETINFOBYNAME_. (See also Procedures With 16-Bit Addressable Parameters (page 69).)
For more details about Guardian procedures, see the Guardian Procedure Calls Reference Manual.
Some procedures in this manual are described as “superseded” by other procedures. For example,
OPEN is superseded by FILE_OPEN_. Superseded procedures do not take full advantage of D-series
or later features and you should not use them. They are provided for backward compatibility only.
Declaring Guardian Procedures
Like all functions in a C program, Guardian procedures must be declared before they can be
called. Guardian procedures are declared as external procedures.
These library header files simplify the declaration of Guardian procedures:
LocationFilenameSystem Type
$SYSTEM.SYSTEMcextdecsGuardian file system
/usr/include/syscextdecs.hOSS
$COMP_ROOT\usr\includecextdecs.hPC
These identical header files contain function prototype declarations for most of the Guardian
procedures that you can call directly from C and C++ programs. These files also correspond to
the TAL and pTAL EXTDECS header file.
Other header files in $SYSTEM.SYSTEM and /usr/include also contain Guardian procedure
declarations. These header files declare Guardian procedures added in D40 or later releases and
include the setjmp, tdmsigh, dlaunchh, and histryh header files.
To determine the header file that declares the procedure, see the procedure’s reference page in
the Guardian Procedure Calls Reference Manual. Each procedure’s reference page includes its C
declaration syntax. However, do not use this syntax to declare Guardian procedures. Include the
appropriate header file instead.
The header files specify the C names for the Guardian procedures in uppercase characters and
provide a section for each procedure using the SECTION pragma. The declarations provided by
the header files follow the guidelines for declaring TAL procedures in Chapter 7: Mixed-Language
Programming for TNS Programs, and for declaring pTAL procedures in Chapter 8: Mixed-Language
Programming for TNS/R and TNS/E Native Programs.
To access declarations in the header files, use the #include directive, specifying as section names
the names of the Guardian procedures you want to include. This example includes the declarations
of the PROCESS_GETINFOLIST_ and FILENAME_FINDNEXT_ procedures:
#include <cextdecs(PROCESS_GETINFOLIST_, FILENAME_FINDNEXT_)>
Many Guardian procedures are written in TAL or pTAL. The header file declarations use the _tal
language-specifier to identify external routines. Native C and C++ programs that call Guardian
procedures must specify the EXTENSIONS pragma, because _tal is an HP extension.
Guardian procedures that use condition codes are declared as procedures returning _cc_status.
Consequently, you must include the header talh (in the Guardian file system) or tal.h (in the
OSS file system) before you call such a Guardian procedure.
66 Interfacing to Guardian Procedures and OSS Functions