Programmschnittstelle GPRBYTE des BS2000-PRNGD

Die Programmschnittstelle GPRBYTE des BS2000-PRNGD steht für die Sprachen C/C++ und ASSEMBLER zur Verfügung.

GPRBYTE ist die Schnittstelle der Routine NLKRES96 im Modul GPRBYTE des DSSM-Subsystems PRNGD. Die Routine NLKRES96 liefert dem Aufrufer Pseudo-Zufallszahlen.

Kompatibilität

Die Programmschnittstelle PRNGD ist source- und objekt-kompatibel ab PRNGD Version 1.0.

Entry-Name(n) und SVC-Nummer(n)

SVC 16 (dezimal)

Makro-Typ

Die folgenden MF-Werte für die Makrogenerierung werden unterstützt (siehe Handbuch „Makroaufrufe an den Ablaufteil“):

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

Der Assembler-Makro und die C/C++-Include-Datei finden sich in der LMS-Bibliothek SYSLIB.PRNGD.nnn.

Makro-Syntax

	Operation	Operanden
<Marke>	GPRBYTE	DATAADR = <datenpufferadresse> ,NUM_BYT = <integer 1..255> / <anzahlbytes> [,MODE = *NON_BLOCKING]

Die Operanden MF und PARAM werden gemäß Konvention unterstützt.

Beschreibung der Operanden

DATAADR = <datenpufferadresse>

Zeiger (char*) auf den Speicherbereich, in den die Zufallszahlen geschrieben werden sollen.

NUM_BYT = { <integer 1..255> | <anzahlbytes> }

Anzahl der Zufalls-Bytes, die in den Speicherbereich geschrieben werden sollen.
Die Anzahl der Zufalls-Bytes kann wie folgt spezifiziert werden:

<integer 1..255>

Ganzzahl zwischen 1 und 255

<anzahlbytes>

Variable vom Datentyp Integer

MODE = *NON_BLOCKING

Betriebsmodus des Zufallszahlen-Generators.
Derzeit wird nur der nicht-blockierende Modus unterstützt, d.h. die Zufallszahlen sollen von einem Generator geliefert werden, der nicht wegen Entropie-Mangels blockiert.

Sprachbesonderheiten

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

Return-Codes

Returncode			Identifier		Bedeutung
SC2	SC1	Maincode		ASS:
0	00	0000	successful	GPRBSUCC	kein Fehler festgestellt
0	20	0001	int_error	GPRBINTE	interner Fehler
0	01	0002	parameter_error	GPRBPARE	Parameterfehler
0	40	0003	buffer_invalid	GPRBBUFE	Puffer zu klein oder nicht allokiert
0	40	0004	too_many_bytes	GPRBTOOM	mehr als 255 Bytes angefordert
0	80	0005	prngd_not_ready	GPRBNRDY	Zufallszahlen-Generator hat nicht genügend Entropie
0	80	0006	timeout	GPRBTOUT	Zufallszahlen-Generator zeitweilig nicht aufrufbar

C-Beispielprogramm

#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);
}