The WILDCARD Tool
The WILDCARD tool is a library of procedures that provide functionality not inherent in any
programming language or environment. Functionally, the WILDCARD library provides solutions
for two common programming tasks. First, it offers the ability to build a fileset from a complex
fileset specification. This ability expands on LISTF-style operations so that you can add, subtract,
or otherwise qualify groups of files for use in your programs. Second, WILDCARD provides a way
to match patterns in string expressions (i.e., filename expressions).
The WILDCARD tool, then, is actually two groups of callable procedures: FILESET procedures
and PATTERN procedures.
The FILESET procedures include:
getfileset
buildfileset
buildfilename
fileseterrmsg
fs_version
The PATTERN procedures include:
pattern_build
pattern_match
pattern_fga_match
check_fga_wildcard
|
|
NOTE POSIX (HFS) file structures are not currently supported.
|
FILESET Procedures
In order to provide maximum flexibility, the FILESET building tasks have been broken into five
separate procedure calls. The generated fileset is stored in an ASCII flat file so that you can
access it as best suits your needs. The section called "Output Format" provides details on the
layout of the file. The complete syntax that can be used to specify a file is described in the section
called "Fileset Syntax". If you are familiar with the MAGNET o BLAZE tools (included in the
System Manager’s Toolbox), then you may be familiar with this syntax already.
The getfileset procedure allows you to build a fileset with a single procedure call. If this call is not
flexible enough for your needs, you may want to use the procedures buildfilename and
buildfileset. These procedures provide more latitude for building the fileset the way you need it.
The remaining procedures, fs_version and fileseterrmsg, are used to provide the version string of
the FILESET procedures and the error text for a specified error code.
FILESET Syntax
This section outlines the syntax used in the various fileset procedures.
Figure 9.1 WILDCARD Extended Fileset Syntax
|
|
NOTE All literals are case-insensitive.
|
For further information, you may wish to refer to Appendix B, which features a list of the more
common file codes, and Appendix C, which provides a convenient reference for LISTF
WILDCARD syntax.
Output Format
This section presents the output format of the FILESET procedures.
File structure: 80 byte, fixed, ASCII
Table 9.1 Output Format
|
Bytes
|
Item
|
|
0 .. 7
|
Account name
|
|
8 .. 15
|
Group name
|
|
16 .. 23
|
File name
|
|
24 .. 28
|
File code
|
|
29 .. 37
|
Record size
|
|
38 .. 41
|
File type
|
|
42 .. 53
|
End-of-file
|
|
54 .. 64
|
File limit
|
|
65 .. 68
|
Blocking factor
|
|
69 .. 79
|
Sectors
|
Operation
All of the FILESET procedures are callable from either Native Mode or Compatibility Mode.
The Native Mode version follows the Procedure Calling Convention established by Hewlett-
Packard and is therefore callable from any language following these conventions.
For Compatibility Mode, follow the rules established by Hewlett-Packard for parameter passing
and segmentation (i.e., not callable from CCS/C CREL format programs).
Two levels of integration are provided so that you can choose the method that best suits your
needs. The first level is simply to call the procedures as you would call an intrinsic. FILESET
procedures can be accessed in much the same manner as intrinsics are accessed. The second
method may be a better choice if a greater level of control is desired. In this case, you would
merge the declaration files into your source, and then recompile and link the program.
GETFILESET
The purpose of this procedure is to build a fileset based on the fileset specification string that is
passed to this procedure.
Syntax:
short int getfileset (expression)
Return Value
getfileset returns a 16-bit integer encoded as follows:
Table 9.2 Getfileset’s Return Values
|
Code
|
Definition
|
Description
|
|
< 0
|
:Error
|
where the absolute value is the error number. This can be passed fileseterrmsg to retrieve the error text.
|
|
0
|
:No error
|
where the resulting fileset is in the temporary file FILES.
|
|
> 0
|
:Warning
|
where the value is the number of characters processed from the provided fileset specification string.
|
Parameters
|
expression
|
Byte array (required). It contains the NULL (ASCII 0) terminated fileset specification string. For a complete discussion of fileset specifications see Appendix C.
|
Operation
To use this routine, all that is required is to declare getfileset as an external procedure.
Depending on the language used, this may occur automatically. Then, compile your application
and link with the either the WILDCARD object file, relocatable library or executable library. After
calling getfileset, check the return value for errors. If no error occurred, the resultant fileset can be
accessed through the temporary file called "FILES".
|
|
NOTE FILES cannot be file equated. See the sample code TESTGFS.C.LPSTOOLS for an example.
|
BUILDFILENAME
This procedure is used to complete the building of the filename based on the specified mode.
Five different modes are available ranging from fully-qualifying the filename to generating a
unique filename. No errors are possible. The filename will be constructed using the standard
MPE filename format (i.e., filename.group.account).
Syntax
buildfilename (filename, mode, terminator);
The Parameter Set is listed next, where each parameter is either an integer, character array, or
integer array.
Table 9.3 BUILDFILENAME’s Parameter Set
|
Parameter
|
Name
|
Type
|
Comment
|
|
1
|
filename
|
character array
|
Required
|
|
2
|
mode
|
short int
|
Required
|
|
3
|
terminator
|
short int
|
Required
|
Return Value
There is no Return Value.
Parameters
|
filename
|
Byte array (required). Modes 0, 1, 2, and 3 contain the space character (ASCII 32) terminated filename. For mode 4, this filename will contain the unique filename generated by the call.
For all modes, the array will be terminated with the character provided in the parameter terminator. The dot (.) separator should not be specified. No filename validation will occur.
|
|
modes
|
Short int (required). Recognized values range from 0 to 4. The definitions are as follows:
0 = Append the logon group and account to the specified filename
1 = Append the logon account to the specified filename
2 = Append the program group and account to the specified filename
3 = Append the program account to the specified filename
4 = Generate a unique filename in logon group
If an unknown mode is given, then the terminator is appended to filename.
|
|
terminator
|
Short int (required). It is used to specify the character that will be used to terminate the byte array filename.
|
Operation
To use this routine, declare buildfilename as an external procedure. Depending on the language,
this may occur automatically. Compile your application and link it with either the WILDCARD
object file, relocatable library or executable library. Before calling buildfilename, determine which
mode you want to use. Then, for modes 0 through 3, initialize the parameter filename. For all
modes, initialize the terminator parameter before calling buildfilename.
The result of all operation will be in the byte array filename. The format for the filename will be in
MPE format. Any values filled in by the call will be in uppercase. Groups, accounts and filenames
will be separated by dots (.). The filename will be terminated with the character specified by the
terminator parameter.
No errors are possible; calling buildfilename with an invalid mode will simply result in the
filename being terminated by the terminator you provided. Also, calling buildfilename without a
filename (for modes 0 through 3) will not cause an error, however, the resulting filename may not
be very useful. For example, see the sample code TESTFS.C.LPSTOOLS or
TESTFS.SPL.LPSTOOLS.
BUILDFILESET
This procedure will generate the fileset specified by the expression. The fileset will be stored in
the file given by the parameter filename and the domain will be determined by the boolean value
of perm. The stat parameter is a two element array. The 0th element contains the status, the 1st
element contains an error code if the 0th element is non-zero. The procedure return value equals
the number of characters processed from the expression parameter.
Syntax
short int buildfileset (expression, filename, perm, stat);
The Parameter Set is listed next, where each parameter is either an integer, character array, or
integer array.
Table 9.4 BUILDFILESET’s Parameter Set
|
Parameter
|
Name
|
Type
|
Comment
|
|
1
|
expression
|
character array
|
Required
|
|
2
|
filename
|
character array
|
Required
|
|
3
|
perm
|
logical
|
Required
|
|
4
|
stat
|
short int
|
Required
|
Return Value
buildfileset returns a 16-bit integer that represents the number of characters processed from the
expression string. Nominally, this equals the length of expression.
Parameters
|
expression
|
Byte array (required). This parameter contains the NULL (ASCII 0) terminated fileset specification string. See the Fileset Specification Syntax in Appendix C for a complete discussion of fileset specifications.
|
|
filename
|
Byte array (required). It contains the NULL (ASCII 0) terminated string used to build a file to hold the result of the buildfileset call. It cannot be file equated.
|
|
perm
|
Logical (required). It contains a value of true (even) or false (odd) used to indicate if the output file should be a permanent or temporary file.
|
|
stat
|
Short int array (required). It contains the status of the call to buildfileset. Stat(0) returns the status of the call. A nonzero value indicates an error. The nonzero code can be optionally passed to fileseterrmsg to retrieve the error text.
|
Operation
To use this routine, declare buildfileset as an external procedure. Depending on the language,
this may occur automatically. Compile your application and link it with either the WILDCARD
object file, relocatable library or executable library. After calling buildfileset, check the status
variable stat to determine if the call was successful. Also, check the return value to determine if
the entire expression was processed. If the variable stat equals zero, then the resultant can be
accessed through the file specified by the parameter filename (see the sample code
TESTFS.C.LPSTOOLS or TESTFS.SPL.LPSTOOLS).
FILESETERRMSG
The purpose of fileseterrmsg is to provide and format the text describing the error returned from
a buildfileset or getfileset call.
Syntax
short int fileseterrmsg (status, buffer);
The Parameter Set is listed next, where each parameter is either an integer array or character
array.
Table 9.5 FILESETERRMSG’s Parameter Set
|
Parameter
|
Name
|
Type
|
Comment
|
|
1
|
status
|
short int array
|
Required
|
|
2
|
buffer
|
character array
|
Required
|
Return Value
The integer value returned by fileseterrmsg is the byte length of the text that has been placed in
buffer.
Parameters
|
status
|
Short int array (required). It contains the status of the call to buildfileset.
status(0) is the error number and it is used to look up the text of the error message.
status(1) (if non-zero) is appended to the end of the error text. The format used is: info: <status(1)>. Its use is purely informational. Most of the time when status(1) is non-zero, it will represent the error number returned by the intrinsic FCHECK plus some kind of file system error.
|
|
buffer
|
Byte array (required). The length must be at least 80 bytes.
|
Operation
To use this entry point, declare fileseterrmsg as an external. Depending on the language, this
may occur automatically. Compile your application and link it with either the WILDCARD object
file, relocatable library or executable library (see the sample code TESTFS.C.LPSTOOLS or
TESTFS.SPL.LPSTOOLS).
FS_VERSION
This procedure will obtain the FILESET version string.
Syntax
fs_version (buffer);
Return Value
There are no Return Values.
Parameters
|
buffer
|
Byte array (required). The length must be at least 80 bytes.
|
Operation
To use this routine, declare fs_version as an external procedure. Depending on the language,
this may occur automatically. Compile your application and link it with either the WILDCARD
object file, relocatable library or executable library. After calling fs_version, the byte array will
contain the ASCII version string. This can be used to test FILESET versions to ensure
compatibility of applications that use FILESET (see the sample code TESTFS.C.LPSTOOLS or
TESTFS.SPL.LPSTOOLS).
Fileset Error Numbers and Meanings
Table 9.6 Fileset Error Numbers and Meanings
|
stat(0)
|
meaning
|
stat(1) meaning
|
|
7
|
error during fclose
|
error number from FCHECK
|
|
8
|
error during fcontrol
|
error number from FCHECK
|
|
9
|
error during fopen, new
|
error number from FCHECK
|
|
10
|
error during fopen, old
|
error number from FCHECK
|
|
11
|
error during fread
|
error number from FCHECK
|
|
12
|
error during file rename
|
error number from FCHECK
|
|
13
|
error saving file
|
error number from FCHECK
|
|
14
|
error during fwrite
|
error number from FCHECK
|
|
21
|
error closing listf temporary file
|
error number from FCHECK
|
|
22
|
error opening listf temporary file
|
error number from FCHECK
|
|
23
|
error reading listf temporary file
|
error number from FCHECK
|
|
|
|
2
|
error from command intrinsic
|
error number from COMMAND
|
|
29
|
error during listf command
|
error number from COMMAND
|
|
|
|
1
|
expected alphabetic or numeric
|
not used
|
|
3
|
expected date
|
not used
|
|
4
|
bad filename part
|
not used
|
|
5
|
bad groupname part
|
not used
|
|
6
|
bad accountname part
|
not used
|
|
15
|
bad 16 bit integer
|
not used
|
|
16
|
same as #1 & # 15
|
not used
|
|
17
|
bad 32 bit integer
|
not used
|
| |
