DitsDefineShared - Defines and optionally creates a shared memory section.

Function

Defines and optionally creates a shared memory section.

Description

Shared memory sections are used by DITS in the handling of bulk data transfers, generally initiated through a call to DitsInitMessBulk(3) or DitsTriggerBulk(3).

These shared memory sections are generally created by the calling routine (in a highly system-dependent way) and then have to be described to DITS so it can use them. For this purpose, DITS has a structure called a 'shared memory information structure' of type DitsSharedMemInfoType. This routine is a utility that can be used by a program that has created such a shared memory section in order to simplify the task of filling out the DitsSharedMemInfoType structure. It has the optional feature that it can also be used to create the structure if it does not yet actually exist. It is also possible to use this routine in a system-independent way to create a temporary shared memory section of a specified size. This can be used by a program that has no particular interest in controlling the details of the shared memory used, but merely wants a shared memory section created.

The parameters for this routine are used quite differently in the different systems for which DITS is implemented, and these system dependent details are described in more detail below. Note that this routine should always be used to initialise an DitsSharedMemInfoType structure, since it will always initialise those elements of the structure defined as being for DITS internal use only, and whose use is not explicitly documented.

Language

Call

(void) = DitsDefineShared (Type, Name, Key, Size, Create, Address, SharedMemInfo, Status)

Parameters

(">" input, "<" output, "!" modified)

>	Type	int	A code used to descibe the mapping type to be used. This must be one of the DITS_SHARE_xxxx codes, see the below.
>	Name	char `*`	Used to identify the mapped section on some machines. On `UNIX`, for example, if mapped files are used, this is the file name in question. If Name is not actually used on the current system it should be passed as a null string.
>	Key	int	On some systems, this is an alternative way of specifying the mapped section. For example, if System V shared memory is used under `UNIX`, this is the identifier for that shared memory.
>	Size	long	The size in bytes of the shared memory section.
>	Create	int	If true, the memory section does not actually exist and this routine is to create it. If this is the case, the Address field of the SharedMemInfo structure will give the address at which the memory section has been mapped, if it is mapped successfully.
`!`	Address	void `**`	On systems with global address spaces, eg. VxWorks, the address of the memory is enough to specify it completely - together with its size. In any case, if the section is already mapped, this argument must specify the address at which it is mapped. If the section is created by this routine, this is returned with the address at which the memory was mapped, which is why this is passed as the address of a void pointer and not just the pointer.
<	SharedMemInfo	DitsSharedMemInfoType `*`	The structure filled by this routine to describe the shared memory section.
`!`	Status	StatusType `*`	Modified status. will be returned.

External variables used

None.

Include Files

DitsBulk.h

Prior requirements

None.

Support

Tony Farrell, AAO.

System-independent use

If Type is set to DITS_SHARE_CREATE, then this call creates a temporary shared memory section of the size specified by Size, in some suitable form for the system it is running on. The caller has no control over the details of the shared memory section. In this case, the Name and Key arguments, and any preset value at the location specified by the Address argument are all ignored. A new section will be created and mapped and the address at which it was mapped will be returned via Address. The Create argument is also ignored, since it is assumed to be set true.

System-dependent details

The following considerations apply when calling this routine on different systems, with Type set to some value other than DITS_SHARE_CREATE.

`VMS`

The mapped section is determined entirely by the Name field, which should be the name of a global page section. Type should be passed as DITS_SHARE_GBLSC. If Type is set to zero, then DITS_SHARE_GBLSC is assumed. Key and Address are ignored.

VxWorks

The mapped section is just a section of memory, starting at a specified address. Type should be DITS_SHARE_GLOBAL. Name should be a Null string, and Key is ignored. If Create is specified, Address is ignored, and a suitably sized area of memory is allocated. If Create is passed as false, then Address should contain the address of the memory section in question. If Type is passed as zero, then DITS_SHARE_GLOBAL is assumed.

`UNIX`

The mapped section can be created as System V shared memory, in which case Type should be DITS_SHARE_SHMEM, or as a file accessed through mmap(), in which case Type should be DITS_SHARE_MMAP. If Type is DITS_SHARE_SHMEM, Key specifies the identifier for the shared memory and Name should be a Null string. If Type is DITS_SHARE_MMAP, Name should be the full name of the file, and Key is ignored. Address is ignored in both cases. If Type is passed as zero, DITS will assume DITS_SHARE_MMAP on systems that support mmap() and will assume DITS_SHARE_SHMEM on other systems.

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tony.farrell@mq.edu.au