GPRBYTE program interface of the BS2000 PRNGD

The GPRBYTE program interface of the BS2000 PRNGD is available for the languages C/C++ and ASSEMBLER.

GPRBYTE is the interface of the NLKRES96 routine in the GPRBYTE module of the DSSM subsystem PRNGD. The NLKRES96 routine supplies the pseudo random numbers for the calling program.

Compatibility

The PRNGD program interface is source- and object-compatible as of PRNGD Version 1.0.

Entry name(s) and SVC number(s)

SVC 16 (decimal)

Macro type

The following MF values are supported for macro generation (see the “Executive Macros” manual):

ASSEMBLER        MF = { C | D | E | L | M }

The ASSEMBLER macro and the C/C++ include file are in the LMS library SYSLIB.PRNGD.nnn.

Macro syntax

	Operation	Operands
<Marker>	GPRBYTE	DATAADR = <data-buffer-address> ,NUM_BYT = <integer 1..255> / <number-of-bytes> [,MODE = *NON_BLOCKING]

The MF and PARAM operands are supported in accordance with the convention.

Operand description

DATAADR = <data-buffer-address>

Pointer (char*) to the memory area to which the random numbers are to be written.

NUM_BYT = { <integer 1..255> | <number-of-bytes> }

Number of random bytes which are to be written to the memory area.
The number of random bytes can be specified as follows:

<integer 1..255>

Integer between 1 and 255

<number-of-bytes>

Variable of the data type integer

MODE = *NON_BLOCKING

Operating mode of the random number generator.
Currently only the non-blocking mode is supported, in other words the random numbers are to be supplied by a generator which is not blocked by lack of entropy.

Special language features

Language	Language-specific operand
ASSEMBLER	[PREFIX = { G | <name> }] [,MACID = { PRB | <name>}] [,EQUATES = { YES | NO }]
C	SVC-#: 16, UNIT = 430, FUNCTION = 1, VERSION = 1

Return codes

Return code			Identifier		Meaning
SC2	SC1	Maincode		ASS:
0	00	0000	successfulGPRBSUCC	GPRBSUCC	No error detected
0	20	0001	int_error	GPRBINTE	Internal error
0	01	0002	parameter_error	GPRBPARE	Parameter error
0	40	0003	buffer_invalid	GPRBBUFE	Buffer too small or not allocated
0	40	0004	too_many_bytes	GPRBTOOM	More than 255 bytes requested
0	80	0005	prngd_not_ready	GPRBNRDY	Random number generator does not have enough entropy
0	80	0006	timeout	GPRBTOUT	Random number generator temporarily unavailable

C programming example

#include <stdio.h>
#include "FHDR.H"
#include "GPRBYTE.H"
main(int argc, char *argv[])
{
  char randomBytes[128];
  struct GPRBYTE_pl_mdl param;
  enum {UNIT = 430, FUNCTION = 1, VERSION = 1, dataLen = 32};
  FHDR_SET_RC_NIL(param.hdr);
  FHDR_MOD_IFID(param.hdr, UNIT, FUNCTION, VERSION);
  param.in_data.mode = GPRBYTEnon_blocking;
  param.in_data.buffer = &randomBytes;
  param.in_data.num_bytes = dataLen;
  GPRBYTEC(param);
  if (param.hdr.FHDR_RC_MAINCODE == GPRBYTEsuccessful) {
    int i;
    printf("GPRBYTEC called successfully\nData: ");
    for (i = 0; i < dataLen; i++)
      printf("%02X", randomBytes[i]);
    printf("\n");
  }
  else
    printf("Error in call of GPRBYTEC: %08X\n", param.hdr.FHDR_RC_NBR);
}