353 lines
20 KiB
HTML
353 lines
20 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="reference" />
|
||
|
|
<meta name="DC.Title" content="Define byte alignment" />
|
||
|
|
<meta name="abstract" content="Correct byte alignment ensures that data used with an API is correct. Byte alignment is also essential when APIs are used to retrieve and then print or display data." />
|
||
|
|
<meta name="description" content="Correct byte alignment ensures that data used with an API is correct. Byte alignment is also essential when APIs are used to retrieve and then print or display data." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="pgmerr.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="conReceiver.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1998, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="pgmerr_bytea" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Define byte alignment</title>
|
||
|
|
</head>
|
||
|
|
<body id="pgmerr_bytea"><a name="pgmerr_bytea"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Define byte alignment</h1>
|
||
|
|
<div><p>Correct byte alignment ensures that data used with an API is correct.
|
||
|
|
Byte alignment is also essential when APIs are used to retrieve and then print
|
||
|
|
or display data.</p>
|
||
|
|
<div class="section"><p>When byte alignment is off, it causes the API to read the data
|
||
|
|
at some point other than at the beginning of a record.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> Read
|
||
|
|
the <a href="codedisclaimer.htm">Code license and disclaimer information</a> for important legal information.</div>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="pgmerr_bytea__bytea_incorrect"><a name="pgmerr_bytea__bytea_incorrect"><!-- --></a><h4 class="sectiontitle">Example of incorrect coding: Defining
|
||
|
|
byte alignment</h4><p>This program illustrates byte alignment while defining
|
||
|
|
a structure. This is shown at <a href="#pgmerr_bytea__SPTRK14A">(1)</a>.
|
||
|
|
Four-byte alignment is required when using this program.</p>
|
||
|
|
<p>Variable-length
|
||
|
|
records must begin on a 4-byte boundary. As shown at <a href="#pgmerr_bytea__SPTRK14A">(1)</a>,
|
||
|
|
the variable-length record CCSID_rec is not beginning on a 4-byte boundary.
|
||
|
|
When the API accesses the CCSID_rec record, 4-byte alignment is forced by
|
||
|
|
padding the first 3 bytes of the CCSID_rec between the replace field and the
|
||
|
|
start of the CCSID_rec record. <a href="#pgmerr_bytea__SPTRK15A">(2)</a> shows
|
||
|
|
that the variable-length record is not 4-byte aligned (the value is 13, which
|
||
|
|
is not divisible by 4). The correct coding is shown at <a href="#pgmerr_bytea__SPTRK17B">(3)</a>.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> Not
|
||
|
|
all APIs require a 4-byte boundary. ILE APIs, such as QusAddExitProgram, do.</div>
|
||
|
|
<pre>/***************************************************************** */
|
||
|
|
/* */
|
||
|
|
/*Program Name: PGM1 */
|
||
|
|
/* */
|
||
|
|
/*Program Language: ILE C */
|
||
|
|
/* */
|
||
|
|
/*Description: This program illustrates improper byte */
|
||
|
|
/* alignment when using variable length */
|
||
|
|
/* records. */
|
||
|
|
/* */
|
||
|
|
/* */
|
||
|
|
/*Header Files Included: <stdio.h> */
|
||
|
|
/* <signal.h> */
|
||
|
|
/* <string.h> */
|
||
|
|
/* <stdlib.h> */
|
||
|
|
/* <qusrgfa1.h> */
|
||
|
|
/* <qusec.h> */
|
||
|
|
/* <qliept.h> */
|
||
|
|
/* */
|
||
|
|
/* APIs Used: QusAddExitProgram - Add an exit program */
|
||
|
|
/* */
|
||
|
|
/********************************************************************/
|
||
|
|
/********************************************************************/
|
||
|
|
/* Includes */
|
||
|
|
/********************************************************************/
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <signal.h>
|
||
|
|
#include <string.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <qusrgfa1.h>
|
||
|
|
#include <qusec.h>
|
||
|
|
#include <qliept.h>
|
||
|
|
/********************************************************************/
|
||
|
|
/* Structures */
|
||
|
|
/* */
|
||
|
|
/********************************************************************/
|
||
|
|
|
||
|
|
typedef struct { /* Error code */
|
||
|
|
Qus_EC_t ec_fields;
|
||
|
|
char exception_data[100];
|
||
|
|
} error_code_struct;
|
||
|
|
|
||
|
|
typedef struct { /* Exit program attribute keys*/
|
||
|
|
int num_rec;
|
||
|
|
Qus_Vlen_Rec_4_t replace_rec;
|
||
|
|
char replace;
|
||
|
|
Qus_Vlen_Rec_4_t CCSID_rec; <span class="uicontrol" id="pgmerr_bytea__SPTRK14A"><a name="pgmerr_bytea__SPTRK14A"><!-- --></a>(1)</span>
|
||
|
|
int CCSID;
|
||
|
|
Qus_Vlen_Rec_4_t desc_rec;
|
||
|
|
char desc[50];
|
||
|
|
} addep_attributes;
|
||
|
|
/********************************************************************/
|
||
|
|
/* */
|
||
|
|
/* main */
|
||
|
|
/* */
|
||
|
|
/********************************************************************/
|
||
|
|
int main()
|
||
|
|
{
|
||
|
|
error_code_struct error_code;
|
||
|
|
addep_attributes attrib_keys;
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Initialize the error code parameter. */
|
||
|
|
/******************************************************************/
|
||
|
|
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Set the total number of exit program attributes that we are */
|
||
|
|
/* specifying on the call. We will let the API take the default */
|
||
|
|
/* for the attributes that we are not specifying. */
|
||
|
|
/******************************************************************/
|
||
|
|
attrib_keys.num_rec=3;
|
||
|
|
/******************************************************************/
|
||
|
|
/* Set the values for the three attributes that we will be */
|
||
|
|
/* specifying: */
|
||
|
|
/* Replace exit program = 1 (CHAR(1) field) */
|
||
|
|
/* Exit program data CCSID = 37 (BIN(4) field) */
|
||
|
|
/* Exit program description='THIS IS A TEST EXIT PROGRAM' */
|
||
|
|
/* (CHAR(50) field) */
|
||
|
|
/* */
|
||
|
|
/* The structure for the exit program attributes defined above is */
|
||
|
|
/* as follows: */
|
||
|
|
/* */
|
||
|
|
/* typedef struct { */
|
||
|
|
/* int num_rec; */
|
||
|
|
/* Qus_Vlen_Rec_4_t replace_rec; */
|
||
|
|
/* char replace; */
|
||
|
|
/* Qus_Vlen_Rec_4_t CCSID_rec; */
|
||
|
|
/* int CCSID; */
|
||
|
|
/* Qus_Vlen_Rec_4_t desc_rec; */
|
||
|
|
/* char desc[50]; */
|
||
|
|
/* } addep_attributes; */
|
||
|
|
/* */
|
||
|
|
/* and the Qus_Vlen_Rec_4_t structure is defined in */
|
||
|
|
/* qus.h (included by qusrgfa1) as: */
|
||
|
|
/* */
|
||
|
|
/* typedef _Packed struct Qus_Vlen_Rec_4 { */
|
||
|
|
/* int Length_Vlen_Record; */
|
||
|
|
/* int Control_Key; */
|
||
|
|
/* int Length_Data; */
|
||
|
|
/* **char Data[];-> this field is supplied by */
|
||
|
|
/* the user */
|
||
|
|
/* } Qus_Vlen_Rec_4_t; */
|
||
|
|
/* */
|
||
|
|
/* This structure is mapped in bytes as follows: */
|
||
|
|
/* { */
|
||
|
|
/* BIN(4) - num_rec */
|
||
|
|
/* BIN(4) - length variable length record for replace key */
|
||
|
|
/* BIN(4) - replace key */
|
||
|
|
/* BIN(4) - length replace data */
|
||
|
|
/* CHAR(1) - replace data */
|
||
|
|
/* BIN(4) - length variable length record for CCSID key */
|
||
|
|
/* BIN(4) - CCSID key */
|
||
|
|
/* BIN(4) - length CCSID data */
|
||
|
|
/* BIN(4) - CCSID data */
|
||
|
|
/* BIN(4) - length variable length record for description */
|
||
|
|
/* key */
|
||
|
|
/* BIN(4) - description key */
|
||
|
|
/* BIN(4) - length description key */
|
||
|
|
/* CHAR(50) - description data */
|
||
|
|
/* } */
|
||
|
|
/* */
|
||
|
|
/******************************************************************/
|
||
|
|
attrib_keys.replace_rec.Length_Vlen_Record=13; <span class="uicontrol" id="pgmerr_bytea__SPTRK15A"><a name="pgmerr_bytea__SPTRK15A"><!-- --></a>(2)</span>
|
||
|
|
attrib_keys.replace_rec.Control_Key=4;
|
||
|
|
attrib_keys.replace_rec.Length_Data=1;
|
||
|
|
attrib_keys.replace='1';
|
||
|
|
|
||
|
|
attrib_keys.CCSID_rec.Length_Vlen_Record=16;
|
||
|
|
attrib_keys.CCSID_rec.Control_Key=3;
|
||
|
|
attrib_keys.CCSID_rec.Length_Data=4;
|
||
|
|
attrib_keys.CCSID=37;
|
||
|
|
|
||
|
|
attrib_keys.desc_rec.Length_Vlen_Record=39;
|
||
|
|
attrib_keys.desc_rec.Control_Key=2;
|
||
|
|
attrib_keys.desc_rec.Length_Data=27;
|
||
|
|
memcpy(&attrib_keys.desc,
|
||
|
|
"THIS IS A TEST EXIT PROGRAM",27);
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Call the API to add the exit program. */
|
||
|
|
/******************************************************************/
|
||
|
|
QusAddExitProgram("EXAMPLE_EXIT_POINT ",
|
||
|
|
"EXMP0100",
|
||
|
|
1,
|
||
|
|
"EXAMPLEPGMEXAMPLELIB",
|
||
|
|
"EXAMPLE EXIT PROGRAM DATA",
|
||
|
|
25,
|
||
|
|
&attrib_keys,
|
||
|
|
&error_code);
|
||
|
|
|
||
|
|
if (error_code.ec_fields.Bytes_Available != 0)
|
||
|
|
{
|
||
|
|
printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION:%.7s",
|
||
|
|
error_code.ec_fields.Exception_Id);
|
||
|
|
exit(1);
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
} /* end program */</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section" id="pgmerr_bytea__bytea_correct"><a name="pgmerr_bytea__bytea_correct"><!-- --></a><h4 class="sectiontitle">Example: Defining byte alignment of correct
|
||
|
|
coding</h4><p>The following example program shows a CHAR(3) bytes reserved
|
||
|
|
field being added to the structure to maintain 4-byte alignment as shown at <a href="#pgmerr_bytea__SPTRK16B">(4)</a>. This corresponds to <a href="#pgmerr_bytea__SPTRK14A">(1)</a> in
|
||
|
|
the incorrect coding example. The 3 reserved bytes are included in the length
|
||
|
|
of the replace variable-length record. <a href="#pgmerr_bytea__SPTRK17B">(3)</a> shows
|
||
|
|
the variable-length record is now 4-byte aligned (record length of 16 is divisible
|
||
|
|
by 4). This corresponds to <a href="#pgmerr_bytea__SPTRK15A">(2)</a> in
|
||
|
|
the incorrect coding example.</p>
|
||
|
|
<pre>/********************************************************************/
|
||
|
|
/* */
|
||
|
|
/*Program Name: PGM2 */
|
||
|
|
/* */
|
||
|
|
/*Program Language: ILE C */
|
||
|
|
/* */
|
||
|
|
/*Description: This program illustrates proper byte */
|
||
|
|
/* alignment when using variable length */
|
||
|
|
/* records. */
|
||
|
|
/* */
|
||
|
|
/* */
|
||
|
|
/*Header Files Included: <stdio.h> */
|
||
|
|
/* <signal.h> */
|
||
|
|
/* <string.h> */
|
||
|
|
/* <stdlib.h> */
|
||
|
|
/* <qusrgfa1.h> */
|
||
|
|
/* <qusec.h> */
|
||
|
|
/* <qliept.h> */
|
||
|
|
/* */
|
||
|
|
/* APIs Used: QusAddExitProgram - Add an exit program */
|
||
|
|
/* */
|
||
|
|
/* */
|
||
|
|
/********************************************************************/
|
||
|
|
/* Includes */
|
||
|
|
/********************************************************************/
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <signal.h>
|
||
|
|
#include <string.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
#include <qusrgfa1.h>
|
||
|
|
#include <qusec.h>
|
||
|
|
#include <qliept.h>
|
||
|
|
/********************************************************************/
|
||
|
|
/* Structures */
|
||
|
|
/********************************************************************/
|
||
|
|
|
||
|
|
typedef struct { /* Error code */
|
||
|
|
Qus_EC_t ec_fields;
|
||
|
|
char exception_data[100];
|
||
|
|
} error_code_struct;
|
||
|
|
|
||
|
|
typedef struct { /* Exit program attribute keys*/
|
||
|
|
int num_rec;
|
||
|
|
Qus_Vlen_Rec_4_t replace_rec;
|
||
|
|
char replace;
|
||
|
|
char Reserved[3]; <span class="uicontrol" id="pgmerr_bytea__SPTRK16B"><a name="pgmerr_bytea__SPTRK16B"><!-- --></a>(4)</span>
|
||
|
|
Qus_Vlen_Rec_4_t CCSID_rec;
|
||
|
|
int CCSID;
|
||
|
|
Qus_Vlen_Rec_4_t desc_rec;
|
||
|
|
char desc[100];
|
||
|
|
} addep_attributes;
|
||
|
|
|
||
|
|
/********************************************************************/
|
||
|
|
/* */
|
||
|
|
/* main */
|
||
|
|
/* */
|
||
|
|
/********************************************************************/
|
||
|
|
int main()
|
||
|
|
{
|
||
|
|
error_code_struct error_code;
|
||
|
|
addep_attributes attrib_keys;
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Initialize the error code parameter. */
|
||
|
|
/******************************************************************/
|
||
|
|
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Set the total number of exit program attributes that we are */
|
||
|
|
/* specifying on the call. We will let the API take the default */
|
||
|
|
/* for the attributes that we are not specifying. */
|
||
|
|
/******************************************************************/
|
||
|
|
attrib_keys.num_rec=3;
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Set the values for the three attributes that we will be */
|
||
|
|
/* specifying: */
|
||
|
|
/* Replace exit program = 1 (CHAR(1) field) */
|
||
|
|
/* Exit program data CCSID = 37 (BIN(4) field) */
|
||
|
|
/* Exit program description='THIS IS A TEST EXIT PROGRAM' */
|
||
|
|
/* (CHAR(50) field) */
|
||
|
|
/******************************************************************/
|
||
|
|
attrib_keys.replace_rec.Length_Vlen_Record=16; <span class="uicontrol" id="pgmerr_bytea__SPTRK17B"><a name="pgmerr_bytea__SPTRK17B"><!-- --></a>(3)</span>
|
||
|
|
attrib_keys.replace_rec.Control_Key=4;
|
||
|
|
attrib_keys.replace_rec.Length_Data=1;
|
||
|
|
attrib_keys.replace='1';
|
||
|
|
|
||
|
|
attrib_keys.CCSID_rec.Length_Vlen_Record=16;
|
||
|
|
attrib_keys.CCSID_rec.Control_Key=3;
|
||
|
|
attrib_keys.CCSID_rec.Length_Data=4;
|
||
|
|
attrib_keys.CCSID=37;
|
||
|
|
|
||
|
|
attrib_keys.desc_rec.Length_Vlen_Record=39;
|
||
|
|
attrib_keys.desc_rec.Control_Key=2;
|
||
|
|
attrib_keys.desc_rec.Length_Data=27;
|
||
|
|
memcpy(&attrib_keys.desc,"THIS IS A TEST EXIT PROGRAM",27);
|
||
|
|
|
||
|
|
/******************************************************************/
|
||
|
|
/* Call the API to add the exit program. */
|
||
|
|
/******************************************************************/
|
||
|
|
QusAddExitProgram("EXAMPLE_EXIT_POINT ",
|
||
|
|
"EXMP0100",
|
||
|
|
1,
|
||
|
|
"EXAMPLEPGMEXAMPLELIB",
|
||
|
|
"EXAMPLE EXIT PROGRAM DATA",
|
||
|
|
25,
|
||
|
|
&attrib_keys,
|
||
|
|
&error_code);
|
||
|
|
|
||
|
|
if (error_code.ec_fields.Bytes_Available != 0)
|
||
|
|
{
|
||
|
|
printf("ATTEMPT TO ADD AN EXIT PROGRAM FAILED WITH EXCEPTION: %.7s",
|
||
|
|
error_code.ec_fields.Exception_Id);
|
||
|
|
exit(1);
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
} /* end program */
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="pgmerr.htm" title="Provides information about common programming errors, as well as examples of correct and incorrect coding.">Common API programming errors</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="conReceiver.htm" title="A receiver variable is a program variable that is used as an output field to contain information that is returned from an API.">Receiver variables</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|