itspec: Manual Page

ITSPEC

NAME

itspec - decode item specification

SYNOPSIS


int     itspec(string,type,match)
char    *string;        /* item type specification */
int32    *datatype;      /* returned type */
char    **subtype;      /* returned subtype match */

DESCRIPTION

An item specification is composed of two parts: an item "datatype" selector and an item "subtype" selector; the routine itspec decodes an item specification into a "datatype" number and a "subtype" match string. The "datatype" number can be specified as a digit string or as a two-character "label" (SP, LX, etc: lower case is automatically converted). The "subtype" match string can consist of one of three alternatives:

".number" the number is taken to be the "subtype" number of the item - usually the occurrence count of the given type in the file.

"^string", "^string^", "=string" the string is taken to be a direct history match on the item required. If no trailing "^" is present, a final "*" is assumed, if the match string ends in a "^", the expression must match the whole of the target expanded history. Matching facilities are described in histmatch(SFS3).

"string" (datatype part=sfslabel, only) the entire specification (with the first two letters in capitals) is taken to be a label code. This code is looked up in the labels file(s) to return a history match string which may then be used to locate an item in the file. See labels(SFS5).

When the "subtype" part of the item specification is not present, itspec returns suitable strings according to the entries in the summary table below:


Input String          Example       Datatype  Subtype Match String

<digit(s)>            5             5         "0"
<digit(s)>.           5.            5         "*"
<digit(s)>.<digit(s)> 5.03          5         "03"
<digit(s)>.^string    5^pitch       5         "pitch*"
<digit(s)>.^string^   5^pitch^      5         "pitch"

<label>               LP            6          "0"
<label>.              LP.           6          "*"
<label>.<digit(s)>    LP.05         6          "05"
<label>^<string>      LP^pitch      6          "pitch*"
<label>^<string>^     LP^pitch^     6          "pitch"
<label><string>       LPpitch       6          "PSapply(*rules=pitch*)" (say)

DIAGNOSTICS

itspec returns 0 on success, 1 on failure.

WARNING

itspec modifies its string argument when the subtype part of the specification is a history match.

NOTE

There is no need to copy the decoded subtype string into another character array following a call to itspec.

VERSION/AUTHOR

2.0 - Mark Huckvale.