gtpc2m6zC/C++ Language Support User's Guide

sonic-Obtain Symbolic File Address Information

Given a symbolic file address this function returns the file address reference format (FARFx) addressing mode and record type of that file address.

Format

#include   <tpfapi.h>
unsigned long sonic(enum  t_lvl  level );

or

#include   <tpfapi.h>
unsigned long sonic(TPF_FA8 *fa8 );

level
A file address reference word (FARW) (D0-DF) containing the symbolic file address being queried.

fa8
A pointer to an 8-byte file address.

Normal Return

Non-zero, with bit settings as described in Table 14.

Table 14. sonic Normal Return

Bit Masks Bit Description
#define SONIC_TYPE_INDICATOR 0x80000000 00 0 = fixed
Nonzero = pool
#define SONIC_POOL_LONGEVITY 0x40000000 01 0 = long-term pool
1 = short-term pool
(See note 1.)
#define SONIC_ADDRESS_FORMAT 0x30000000 02-03 00 = FARF3 addressing format
01 = FARF4 addressing format
11 = FARF5 addressing format
10 = FARF6 addressing format
  04-06 0
#define SONIC_FADDR_INVALID 0x01000000 07 0 = Valid file address
1 = Invalid file address
  08-15 0
#define SONIC_RECORD_UNIQUE 0x00008000 16 0 = address is common to all SSUs/
processors/I-streams of the caller's
subsystem
1 = address is unique to some
combination of SSUs/processors/
I-streams in the subsystem.
(See note 2.)
#define SONIC_ALT_REC_SIZE 0x00004000 17 0 = size is indicated by bit 31 alone
1 = size is 4K (4096) bytes
Bit 31 should also = 1
  18-27 0
Pool address indicator 28 0 = fixed address
1 = pool address
(See note 3.)
#define SONIC_DUPLICATED 0x00000004 29 0 = not duplicated/no fallback
1 = duplicated/fallback
  30 Always set to 1
#define SONIC_REC_SIZE 0x00000001 31 0 = small size record (381 bytes)
1 = large size record
(1055 or 4096 bytes)
Notes:
  1. This bit is meaningful only when the file address is a pool address (that is, bit 0 = 1); otherwise, it is zero.
  2. This bit is meaningful only when the file address is a fixed address (that is, bit 0 = 0).
  3. This bit has no equate associated with it. It is always set to 1 to maintain compatibility with an earlier interface.

Error Return

The SONIC_ERROR tag is defined for interrogating the error return.

SONIC_ERROR
The return code if the FARF address input is invalid.

SNAPC with the error number OPR-074 will be issued when NO_LVL was specified for the one required parameter, or if an invalid data level value was encountered. The ECB is exited when the dump is taken.

Programming Considerations

Examples

The following example returns the file characteristics of the FARF address in data level 4.

#include <tpfapi.h>
unsigned long ret_code;

  ·
  ·
  ·
ret_code = sonic(D4);

The following example returns the file characteristics of the 8-byte FARF address.

#include <tpfapi.h>
unsigned long ret_code;
TPF_FA8	fa8;

  ·
  ·
  ·
ret_code = sonic(&fa8);

Related Information

tpf_esfac-Obtain Extended Symbolic File Address Information