Previous chapter is Chapter 3, "The C Interface to External Functions".
This chapter contains sections that describe the components of the API in alphabetical order.
OMXF_int OMXF_API_VersionNumber
The numeric constant, OMXF_API_VersionNumber, is used as an argument to OMXF_CheckOmniMarkVersion to determine whether the API compiled into the dynamic library is compatible with the version of OmniMark that is running.
char * OMXF_API_VersionString
The string constant, OMXF_API_VersionString, contains a string representation of the complete identification of the OmniMark External Function API, including the version number. It is useful for informational messages.
This data type will store a character. It is an unsigned data type and it has no defined fixed size. It will be the size appropriate to the system that OmniMark is running on and the version of OmniMark that the library was compiled to interface to. This defintion provides OmniMark Technologies Corporation and its customers the maximum amount of flexibility for future enchancements.
The programmer can not depend on the current size of this data type. Whenever an array of C characters must be copied to an array of OMXF_char, each character should be copied individually from the first array to the second. The same applies for the reverse conversion. Do not simply cast the pointers! Casting the pointers can cause unpredictable results if the size of OMXF_char changes in the future. By following this simple rule, external function libraries will run correctly no matter what future developments occur.
This data holds a 32 bit signed number on all platforms and for all future versions of OmniMark.
This structure defines the header of each OPAQUE value for this release. Do not depend on the size or layout of this header being the same for all external function libraries! Libraries compiled with different releases of the OmniMark External Function API may use different structure definitions.
OMXF_String_types are variable length data structures. Although the field OMXF_S_String is defined as an array of a single item, the array can actually be any size. It is not OmniMark's intention that programmers will directly allocate these strings. To that end, the set of methods described above has been provided.
This type represents the possible classes an argument can be declared as in the OmniMark program.
This type represents the possible types an argument can be declared as in the OmniMark program.
Every object has a field of this type internally. It indicates whether the last method called on this object succeeded, and if not, why it failed. This field is initialized to OMXF_fi_Success when the object is created. The only method which does not change this field is OMXF_GetFailureIndicator.
Success
Method Interfaces
Shelves
Sources
Opaque types
OmniMark Environment
Storage Management
Stream Item Operation Failures
Stream Option Failures
The OMXF_OptionBlockFormatModifier_type is used solely in conjunction with the OMXF_SetFormatModifiers and OMXF_ClearFormatModifiers methods on OMXF_StreamOpenOptionBlock_type objects. The values of the type are used to set or clear the options available when opening a stream. There is no need to set these options if the default behavior is what is required. The default behavior is that no format modifiers are active.
Do not rely on the numeric values of the symbolic names of the type as they are subject to change without notice.
To find out about the meaning of the format modifiers below, refer to the regular OmniMark documentation. OMXF_obfm_H_FormatModifier corresponds to the "h" format modifier, OMXF_obfm_L_FormatModifier corresponds to the "l" format modifier, etc.
The enumerated type OMXF_ReturnValueType_type represents the possible types that an external function can return.
The enumerated type OMXF_StreamAttachmentType_type represents the possible types of objects to which a STREAM can be attached. Put another way, this type indicates where values written to a STREAM end up. If the STREAM item is not attached, OMXF_GetTypeOfStreamItemAttachment returns OMXF_sat_Failure.
The enumerated type OMXF_StreamState_type indicates the different states that a STREAM can be in. A value of this type is returned by OMXF_GetStateOfStreamItem.
This is a representation of SWITCH values which are passed into and returned from OMXF_SwitchShelf_type methods. The programmer must not assume that they correspond to particular numeric values. Libraries might not run under future versions of OmniMark otherwise.
Methods:
These are the methods which are common to all OmniMark External Function Interface objects.
Where a function has an argument of type object type, it means that the function will accept more than one type of object taken from the following list (but not all functions accept all types of objects):
Inherits methods from Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object provides methods for signaling exceptions from External Functions and subfunctions. In effect, the application programmer uses this API to indicate to the OmniMark program that a failure of some sort has occurred within the external function. Upon returning from the external function, OmniMark will terminate the program with a fatal error.
The application programmer must provide a "reason" for the exception in the form of a null-terminated "C" string. This string is incorporated into the message displayed by OmniMark when it terminates. The reason must be given, even if it is only a zero-length string.
Inherits methods from Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
These are the methods which are common to all types of shelf objects.
Inherits methods from Shared Base Methods.
Additional Methods:
The OmniMark External Function Interface expects to receive character data in one of two ways, depending on the context. When the external function is writing data to a OMXF_StreamShelf_type, the amount of data can be quite large and is usually transient. For this purpose, the external function uses a OMXF_Sink_type as the agent through which the data is written. The interface of the OMXF_Sink_type is geared towards moving large amounts of data efficiently.
OmniMark also uses smaller character strings in many ways. They can be used as filenames, shelf item keys, or function argument names. In the future, they will be used for other things as well.
Because the zero-valued character is permitted in OmniMark strings, the length of an OmniMark string must always be indicated explicitly. This can be inconvenient when the data is in a C string (terminated by a zero character value). Other sources for these small character strings may be C character arrays which could perhaps contain a zero character.
To accommodate all of these possible character sources in every method which requires a small string as an argument would clutter the interface. The problem gets worse geometrically if any method takes two or more such arguments.
The OmniMark External Function Interface avoids this escalating complexity by providing a data structure called a OMXF_String_type that holds the character string as an array of OMXF_chars and provides a field to specify the length of the array explicitly.
To make it more convenient to use these OMXF_String_types, the OmniMark External Function Interface provides methods to allocate, initialize and free them. Allocation and initialization are always done simultaneously. The OMXF_String_type can be initialized from any of the sources listed above: a zero-terminated C string, an array of C chars, or an array of OMXF_chars.
OMXF_String_types can be allocated with two kinds of lifespans. Most OMXF_String_types will remain available until they are explicitly freed by OMXF_Free_OMXF_String, or until the external function returns. At that point, OmniMark will free any remaining unfreed OMXF_String_types.
Sometimes, though, the programmer will only need to use the OMXF_String_type once, and can then throw it away. To avoid the expense of allocating and freeing memory for such a disposable OMXF_String_type, the OmniMark External Function Interface provides a single "temporary" OMXF_String_type. Each time the temporary OMXF_String_type is initialized, the space is reused if possible. However, the external function programmer must not count on the new OMXF_String_type being in the same memory location as the old one. So whenever the temporary OMXF_String_type is reinitialized, the old pointer should be discarded.
Typedef: OMXF_ArgumentInfo_type.
Inherits methods from Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object provides the methods used to find out information about the various arguments passed to the external function, without necessarily knowing in advance their types, names, or even how many arguments the function was declared with. This object is useful for supporting generic functions. The following example shows how an OmniMark program maps two completely different functions to the same external function:
define external counter function fc
read-only stream s1
and value counter c2 optional
as "f" in function-library "f.so"
define external function fv (
value counter i
, modifiable stream j
and-then value switch k optional
picked-up-by remainder counter l and ...
) as "f"
in function-library "f.so"
An implementor of the function "f" from this example could use the the following methods to determine how to process the arguments and what to return.
Typedef: OMXF_CounterShelf_type.
Inherits methods from Shared Shelf Methods, Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object encapsulates a COUNTER shelf.
Typedef: OMXF_Environment_type.
Inherits methods from Shared Exception Handler Methods, Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object encapsulates the environment from which the OmniMark external function was called. It provides access to the argument shelves, the return value, and the current output streams. It is intended to be a window into the OmniMark run-time environment.
Typedef: OMXF_ExternalOutputOptions_type.
Inherits methods from Shared Base Methods.
Additional Methods:
This object provides methods that allow the application programmer to inquire about the options that were used to open the "external output stream". The following stream options can be queried:
This information can then be saved in the "persistent data object" of the OMXF_ExternalOutput_type for use by subfunctions, or used immediately.
Typedef: OMXF_ExternalOutput_type.
Inherits methods from Shared Base Methods.
Additional Methods:
This object is created by an external output function. External output functions can be attached to an OmniMark stream when the stream is opened.
This object contains subfunctions which allow the external output stream to have all the behaviour of a "regular" OmniMark stream. The external output stream must associate these subfunctions with C functions using the methods provided.
In some cases a subfunction can be a "noop", simply returning and doing nothing, as in the case that no action is required on a CLOSE. In other cases a subfunction can simply return an error, as in the case that it is meaningless to create a source that returns the stream's contents. If the external function does not set a particular subfunction, a pre-defined (default) subfunction is used for that subfunction.
This object can also point to a "persistent data" object. This data structure is defined and created by the application programmer to allow the externally-defined output stream to retain state information and information about the resources it uses between subfunction calls. Every time a subfunction is called, a pointer to this structure will also be passed. The subfunction can update the "persistent data" structure in any way it wishes.
Typedef: OMXF_ExternalSource_type.
Inherits methods from Shared Base Methods.
Additional Methods:
This object is created by an external source function. External source functions can be processed by OmniMark's pattern-matching in the same way as files or string expressions can. These objects return input data to OmniMark as it is required, allowing a huge amount of data to be scanned without needing to store all of it in memory at once.
This object contains subfunctions which allow the external input source to have all the behaviour of a "regular" OmniMark stream. The external input source must associate these subfunctions with C functions using the methods provided.
In some cases a subfunction can be a "noop", simply returning and doing nothing, as in the case that no action is required on a CLOSE. In other cases a subfunction can simply return an error, as in the case that it is meaningless to create a source that returns the stream's contents. If the external function does not set a particular subfunction, a pre-defined (default) subfunction is used for that subfunction.
Buffering of text read from an externally-defined source for the purposes of pattern matching is done by OmniMark. Likewise, keeping track of the location information in the source is done by OmniMark.
This object can also point to a "persistent data" object. This data structure is defined and created by the application programmer to allow the externally-defined source to retain state information and information about the resources it uses between subfunction calls. Every time a subfunction is called, a pointer to this structure will also be passed. The subfunction can update the "persistent data" structure in any way it wishes.
Typedef: OMXF_OpaqueShelf_type.
Inherits methods from Shared Shelf Methods, Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This shelf encapsulates arguments which are defined as OPAQUE arguments.
Typedef: OMXF_Sink_type.
Inherits methods from Shared Base Methods.
Additional Methods:
This object provides the methods to write values to an open stream. They provide the same sort of functionality that the current output stream stack does. Streams that are pushed onto a stream stack cannot be closed, opened, re-opened, or have an item removed or the shelf cleared. Correspondingly, streams which have an associated OMXF_Sink_type object also cannot be closed, opened, re-opened, or have a shelf item removed or the shelf cleared. An open STREAM item can have an unlimited number of OMXF_Sink_type objects associated with it. If the application programmer does not free the OMXF_Sink_type object before returning from the external function, OmniMark will garbage-collect it. OmniMark, however, will not close the STREAM item. You will corrupt OmniMark if you do so.
The methods associated with this object are:
Typedef: OMXF_Source_type.
Inherits methods from Shared Base Methods.
Additional Methods:
This object provides the methods used to retrieve the contents of a closed STREAM item. The OMXF_Source_type object does an implicit copy of the data when it is created. This means that if the application programmer opens the STREAM shelf item associated with the OMXF_Source_type object this will not affect reading from the OMXF_Source_type object. The only caveat is, if the STREAM is attached to a file and the application programmer modifies the file while reading from the STREAM's OMXF_Source_type object, the result would be operating system dependent.
The methods associated with this object are:
Typedef: OMXF_StreamOpenOptionBlock_type.
Inherits methods from Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
If the application programmer wishes to use options other than the defaults when opening or closing a stream, they must supply a pointer to an option block that contains the desired options. An option block is obtained by using the OMXF_StreamShelf_type method OMXF_AllocateStreamOpenOptionBlock.
The open and reopen methods do not currently support any options. As options are introduced, methods will be added to the OMXF_StreamOpenOptionBlock_type class to set and clear those options.
Typedef: OMXF_StreamShelf_type.
Inherits methods from Shared Shelf Methods, Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object encapsulates a STREAM shelf. STREAM shelves support a much richer set of operations than the other shelf types, and the methods for this object reflect that.
Typedef: OMXF_SubEnvironment_type.
Inherits methods from Shared Exception Handler Methods, Shared String Allocator Methods and Shared Base Methods.
This object encapsulates a mini environment that is passed to the subfuctions that are associated with OMXF_ExternalOutput_type and OMXF_ExternalSource_type objects.
Typedef: OMXF_SwitchShelf_type.
Inherits methods from Shared Shelf Methods, Shared String Allocator Methods and Shared Base Methods.
Additional Methods:
This object encapsulates a SWITCH shelf.
void OMXF_Connect_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo)
This subfunction is only used by OMXF_ExternalOutput_type objects.
The OMXF_Connect_fun prepares the external output stream for writing. It is called just once prior to the very first "write" or "disconnect".
void OMXF_Disconnect_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo)
This subfunction is only used by OMXF_ExternalOutput_type objects.
The OMXF_Disconnect_fun indicates that the external output stream will no longer be written to. For instance, it is called when the stream is closed or when it is about to go out of scope.
void OMXF_HasName_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo,
OMXF_int * p_YesOrNo)
This subfunction is only used by OMXF_ExternalOutput_type objects.
OMXF_HasName_fun indicates to OmniMark whether or not the external output stream has a name. The location pointed to by "p_YesOrNo" should be set to a non-zero value to indicate that the stream has a name. Otherwise, it should be set to zero.
void OMXF_NameLength_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo,
OMXF_int * p_NameLength)
This subfunction is only used by OMXF_ExternalOutput_type objects.
OMXF_NameLength_fun returns to OmniMark the length of the name of the external output stream (if it has one).
The location pointed to by "p_NameLength" should be set to the length of stream name. The subfunction should signal an exception if the output stream has no name.
void OMXF_NameOf_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo,
OMXF_char * p_NameDataBuffer,
OMXF_int MaximumDataBufferSize,
OMXF_int * p_AmountWrittenToDataBuffer)
This subfunction is only used by OMXF_ExternalOutput_type objects.
OMXF_NameOf_fun returns to OmniMark the name of the external output stream (if it has one).
The subfunction can write up to "MaximumDataBufferSize" of text in the location pointed to by "p_NameDataBuffer". The location pointed to by "p_AmountWrittenToDataBuffer" should be set to the amount of text that was actually written to the data buffer. The subfunction should signal an exception if the output stream has no name.
OMXF_OpaqueHeader_type * OMXF_OpaqueCopy_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
OMXF_OpaqueHeader_type * p_Obj)
This subfunction is called by OmniMark when it needs to copy an OPAQUE value of a particular type.
OMXF_OpaqueHeader_type * OMXF_OpaqueCreator_fun
(OMXF_SubEnvironment_type * p_SubEnvironment)
This subfunction is defined here just to illustrate its prototype. The typedef for this subfunction is not actually used.
void OMXF_OpaqueRelease_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
OMXF_OpaqueHeader_type * p_Obj)
This subfunction is called by OmniMark when it needs to release an OPAQUE value of a particular type.
void OMXF_Read_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo,
OMXF_int AmountOfDataToRead,
char * p_InputDataBuffer,
OMXF_int * p_AmountThatWasRead)
This subfunction is only used by OMXF_ExternalSource_type objects.
OMXF_Read_fun is called to provide data to OmniMark. It can supply up to "AmountOfDataToRead" of input text to OmniMark in the data buffer pointed to by "p_InputDataBuffer". The location pointed to by "p_AmountThatWasRead" should be set to the amount of text that was stored in the data buffer. When the amount of text stored is zero, OmniMark assumes that the end of input has been reached.
void OMXF_Reconnect_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo)
This subfunction is only used by OMXF_ExternalOutput_type objects.
The OMXF_Reconnect_fun prepares the external output stream for writing after having been disconnected. It is called just prior to the first "write" following a disconnect.
void OMXF_Terminate_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo)
This subfunction is used by both OMXF_ExternalOutput_type and OMXF_ExternalSource_type objects.
OMXF_Terminate_fun terminates the lifetime of the external output or source stream. Any resources it is using must be released. A "terminate" occurs when a stream actually goes out of scope, and, in general, will be preceded by a "close" if the stream is connected. The terminate subfunction is guaranteed to be called when no further references to the output stream exist.
The primary function of the "Terminate" subfunction is to "close" any external file, socket or other connection from which the source (stream) was getting (putting) data. It can also be used to free up other system resources. OmniMark guarantees that the "Terminate" subfunction of an externally-defined source or stream is always called.
void OMXF_Write_fun
(OMXF_SubEnvironment_type * p_SubEnvironment,
void * p_UserInfo,
char * p_OutputDataBuffer,
OMXF_int AmountInDataBuffer)
This subfunction is only used by OMXF_ExternalOutput_type objects.
OMXF_Write_fun writes data to the external output stream (from a PUT action, for example).
The "Write" subfunction is called when the external output stream should accept "AmountInDataBuffer" of text that is provided by OmniMark in the buffer pointed to by "p_OutputDataBuffer".
OMXF_StreamOpenOptionBlock_type * OMXF_AllocateStreamOpenOptionBlock
(OMXF_StreamShelf_type * p_Obj)
Returns a pointer to a OMXF_StreamOpenOptionBlock_type. The object is initialized to the default options for both open and reopen methods. This option block may be freed explicitly by OMXF_FreeStreamOpenOptionBlock. Otherwise it will be garbage-collected when the external function returns.
OMXF_int OMXF_ArgumentIsOptional
(OMXF_ArgumentInfo_type * p_Obj)
This method returns 0 if the indicated argument is not optional, and a non-0 value if it is optional.
OMXF_int OMXF_ArgumentIsSpecified
(object type * p_Obj)
Failure possibility:
The method is used to determine whether or not an argument is using a defaulted value or the value specified in the call to the function.
The method return a non-zero value if the shelf in question was given an explicit value in the function call, and zero if the value of the shelf represents a default value as specified in the declaration of the function.
Note that this question only applies to OPTIONAL function arguments. If this method is used on a shelf that is not OPTIONAL, it returns a non-zero value and the failure code OMXF_fi_ArgumentNotOptional is set on the shelf in question.
OMXF_int OMXF_CheckOmniMarkVersion
(object type * p_Obj,
OMXF_int API_Version)
This method checks whether OmniMark supports the given API version. The API_Version must be obtained from the macro OMXF_API_VersionNumber. This method returns a non-zero value if the version of OmniMark and the OmniMark External Function Interface are compatible, and zero if not.
OMXF_int OMXF_ClearFormatModifiers
(OMXF_StreamOpenOptionBlock_type * p_Obj,
OMXF_int ModifierValue)
Failure possibilities:
This method works exactly like OMXF_SetFormatModifiers, except it is used to deactivate format modifiers rather than activating them. Since the default behavior for a stream is to have no format modifiers activated, it is only necessary to use this method if an option block has been used to open streams with activated format modifiers and now needs to be used to open streams with fewer or other format modifiers activated.
OMXF_int OMXF_ClearShelf
(object type * p_Obj)
Failure possibilities:
This method removes all of the items on the specified shelf. If the method succeeds, it will return a non-zero value. Otherwise, zero will be returned, and the shelf will be unchanged.
OMXF_int OMXF_CloseStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method closes the specified STREAM shelf item. If the method succeeds, it returns a non-zero value. If the method fails the STREAM item is not closed and it returns zero in that case.
OMXF_String_type * OMXF_CopyCharArrayToTmp_OMXF_String
(object type * p_Obj,
OMXF_int CharArrayLength,
const char * p_CharArray)
Failure possibilities:
This method returns a pointer to the temporary OMXF_String_type data structure, initialized from the specified zero-terminated C string. The contents of the temporary OMXF_String_type are lost the next time it is initialized.
If the method fails, it returns a null pointer.
OMXF_String_type * OMXF_CopyCharArrayTo_OMXF_String
(object type * p_Obj,
OMXF_int CharArrayLength,
const char * p_CharArray)
Failure possibilities:
This method allocates and returns a pointer to a OMXF_String_type data structure, initialized from the specified number of C chars from the specified array. The OMXF_String_type can either be freed explicitly by OMXF_Free_OMXF_String, or it can be left to be garbage-collected when the external function returns.
If the method fails, it returns a null pointer.
OMXF_String_type * OMXF_Copy_C_StringToTmp_OMXF_String
(object type * p_Obj,
const char * p_CString)
Failure possibility:
This method returns a pointer to the temporary OMXF_String_type data structure, initialized from the specified number of C chars in the specified array. The contents of the temporary OMXF_String_type are lost the next time it is initialized.
If the method fails, it returns a null pointer.
OMXF_String_type * OMXF_Copy_C_StringTo_OMXF_String
(object type * p_Obj,
const char * p_CString)
Failure possibility:
This method allocates and returns a pointer to a OMXF_String_type data structure, initialized from the specified zero-terminated C string. The OMXF_String_type can either be freed explicitly by OMXF_Free_OMXF_String, or it can be left to be garbage-collected when the external function returns.
If the method fails, it returns a null pointer.
OMXF_ExternalOutput_type * OMXF_CreateExternalOutput
(OMXF_Environment_type * p_Obj)
This method creates a OMXF_ExternalOutput_type object and returns a pointer to it. This object is an "external output stream" which can be attached to an OmniMark stream or it can be set as the return value of an external function whose return value type is an externally-defined output stream. The externally defined output stream is an "object", with subfunctions defined to allow the external definition to receive text written to its stream, as well as providing REOPEN functionality and the ability to return the text written to it.
If the application programmer does not free the OMXF_ExternalOutput_type objects before returning from the external function OmniMark will garbage-collect them.
If the method succeeds it returns a non-zero value, otherwise it returns zero.
OMXF_ExternalSource_type * OMXF_CreateExternalSource
(OMXF_Environment_type * p_Obj)
This method creates a OMXF_ExternalSource_type object and returns a pointer to it. OmniMark provides the means for an externally-defined function to define a "source", to which pattern matching can be defined. An externally-defined source is an "object", with "subfunctions" defined to allow the external definition to provide input text as it is required by OmniMark, and "persistent data" to allow the subfunctions to keep track of where they are in the process of providing input text.
If the application programmer does not free the OMXF_ExternalSource_type objects before returning from the external function, OmniMark will garbage-collect them.
If the method succeeds it returns a non-zero value, otherwise it returns zero.
OMXF_int OMXF_DiscardReturnValue
(OMXF_Environment_type * p_Obj)
Failure possibility:
This method discards the current return value. The result is as if the return value was never set.
The method returns a non-zero value when it succeeds and zero when it fails.
OMXF_int OMXF_DiscardStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method discards the contents of the STREAM and sets the STREAM to the UNATTACHED state. If the method succeeds, it returns a non-zero value. If the method fails it returns zero and does not change the contents or the state of the stream.
OMXF_FreeExternalOutput
(OMXF_ExternalOutput_type * p_Obj)
This method frees the OMXF_ExternalOutput_type object. The object should not be used again.
OMXF_FreeExternalSource
(OMXF_ExternalSource_type * p_Obj)
This method frees the OMXF_ExternalSource_type object. The object should not be used again.
OMXF_FreeSink
(OMXF_Sink_type * p_Obj)
This method breaks the association between the OMXF_Sink_type object and an open STREAM shelf item and frees the OMXF_Sink_type object. The object should not be used again.
OMXF_FreeSource
(OMXF_Source_type * p_Obj)
This method frees the specified OMXF_Source_type object.
OMXF_FreeStreamOpenOptionBlock
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method frees the option block. An option block cannot be used after it is freed.
OMXF_int OMXF_Free_OMXF_String
(object type * p_Obj,
OMXF_String_type * p_OMXF_String)
Failure possibility:
This method frees the OmniMark String and returns a non-zero OMXF_int value if the string was allocated by OmniMark. If the method fails it will return zero.
OMXF_int OMXF_GetAppendingOptionValue
(OMXF_ExternalOutputOptions_type * p_Obj)
This method returns an integer value indicating whether the stream was opened with OPEN (zero value) or REOPEN (non-zero value).
OMXF_ArgumentClass_type OMXF_GetArgumentClass
(OMXF_ArgumentInfo_type * p_Obj)
This method returns a value indicating the class of the specified argument. It can be used to determine if an argument is defined to be VALUE, READ-ONLY, MODIFIABLE, or REMAINDER.
OMXF_ArgumentInfo_type * OMXF_GetArgumentInfo
(object type * p_Obj)
This method return a pointer to an object that encapsulates information about the argument associated with the given shelf.
OMXF_ArgumentInfo_type * OMXF_GetArgumentInfoByPosition
(OMXF_Environment_type * p_Obj,
OMXF_int ArgPosition)
Failure possibility:
This method returns a pointer to an object encapsulating the particular argument. The methods described in OMXF_ArgumentInfo_type can then be used to determine more information about the argument.
OMXF_Source_type * OMXF_GetArgumentName
(OMXF_ArgumentInfo_type * p_Obj)
This method returns a pointer to a OMXF_Source_type object which contains the OmniMark name of the specified argument. This method always succeeds. The initial length will always be available from the returned OMXF_Source_type.
OMXF_ArgumentObjectType_type OMXF_GetArgumentObjectType
(OMXF_ArgumentInfo_type * p_Obj)
This method returns a value that can be used to determine the type how the argument was declared, and can then be used to decide how to access the variable's value.
OMXF_int OMXF_GetArgumentPosition
(OMXF_ArgumentInfo_type * p_Obj)
This method returns the ordinal position of the argument in the argument list, from left to right as declared in the OmniMark program. The first argument has position 1, the second 2, etc. Optional arguments that are not specified occupy a position; they just don't have a value or shelf associated with them.
OMXF_Source_type * OMXF_GetArgumentTypeName
(OMXF_ArgumentInfo_type * p_Obj)
This method returns a pointer to a OMXF_Source_type object which contains the OmniMark name of the type of the specified argument. This method always succeeds. The initial length will always be available from the returned OMXF_Source_type. Note that OMXF_GetArgumentObjectType on an argument returns OMXF_rvt_Opaque, then this method will return the name of the opaque type, and not the string "OPAQUE". Otherwise, the method will return the name of the argument's type.
OMXF_int OMXF_GetBinaryOrderingValue
(OMXF_ExternalOutputOptions_type * p_Obj)
This method returns an integer value representing the binary conversion code (as in WITH BINARY) for the specified output stream.
OMXF_CounterShelf_type * OMXF_GetCounterArgument
(OMXF_Environment_type * p_Obj,
const OMXF_String_type * p_ArgumentName)
Failure possibilities:
This method returns a pointer to an object encapsulating the COUNTER argument with the specified name. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_CounterShelf_type * OMXF_GetCounterArgumentByPosition
(OMXF_Environment_type * p_Obj,
OMXF_int ArgumentNumber)
Failure possibilities:
This method returns a pointer to an object encapsulating the COUNTER argument at the specified position in the declared argument list. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_int OMXF_GetCounterItemValue
(OMXF_CounterShelf_type * p_Obj,
OMXF_int CounterItemIndex)
Failure possibility:
This method returns the value of the specified shelf item. The method always returns zero if it fails, but zero can also be returned when the method succeeds. If the method returns non-zero, the application programmer can be sure it succeeded. If it returns zero, the failure indicator must be checked to determine whether the method succeeded and the value of the item is zero, or whether the method failed.
OMXF_int OMXF_GetDefaultItem
(object type * p_Obj)
Failure possibility:
This method returns the item number of the contextually selected ("default") shelf item. It always succeeds.
The default item is not guaranteed to be on the shelf. For instance, a shelf with zero items does not contain its default item.
In order to determine whether the default item is on the shelf, the programmer must check that the returned value is between 1 and the number of items on the shelf, inclusive. The number of items can be determined using the method OMXF_GetNumberOfShelfItems.
OMXF_ExternalOutputOptions_type * OMXF_GetExternalOutputOptions
(OMXF_Environment_type * p_Obj)
Failure possibility:
This method return a pointer to a OMXF_ExternalOutputOptions_type object. This object supplies methods that allow the application programmer to inquire about the options that were used to open the associated "external output stream".
If the method succeeds it returns a non-zero value, otherwise it returns zero.
OMXF_FailureIndicator_type OMXF_GetFailureIndicator
(object type * p_Obj)
This method returns the value of the object's failure indicator. This value is updated everytime a method is called. The value returned indicates if the method failed and why. This method cannot fail and does not set the failure indicator. (i.e. Two calls to OMXF_GetFailureIndicator on an object with no methods invoked on the object in between will always return the same failure indicator value.)
OMXF_int OMXF_GetInitialLengthOfSource
(OMXF_Source_type * p_Obj)
Failure possibility:
This method will retrieve the initial length of the OMXF_Source_type object if it is available. If the length is available the method returns the length and sets the failure indicator to OMXF_fi_Success. If it is not available, zero will be returned and the failure indicator will be set to OMXF_fi_LengthNotAvailable. Note that zero could also be returned as a valid length, so the caller must not assume that zero indicates failure. If zero is returned, the failure indicator must be checked to determine whether it means a length of zero or whether it is a consequence of the length not being available.
OMXF_int OMXF_GetItemNumberOfKey
(object type * p_Obj,
const OMXF_String_type * p_Key)
Failure possibilities:
This method returns the item number of the shelf item which is associated with the key. If the method succeeds, it will return a value greater than zero. If the method fails it returns zero.
OMXF_Source_type * OMXF_GetKeyOfShelfItem
(object type * p_Obj,
OMXF_int ShelfItemIndex)
Failure possibilities:
This method returns a pointer to a OMXF_Source_type object which contains the key of the specified shelf item if it succeeds. If it fails, it returns a null pointer value. The initial length of the OMXF_Source_type will always be available from the returned object.
OMXF_int OMXF_GetLengthOfStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method attempts to return the length of the object currently attached to the stream. If the method succeeds, it will return the length of the object which may be zero. If it fails, it returns zero. If a non-zero value is returned, the application programmer can be confident that the method succeeded. If a zero value is returned, the programmer must check the failure indicator to determine whether the method succeeded or failed.
OMXF_Source_type * OMXF_GetNameOfOmniMarkFunction
(OMXF_Environment_type * p_Obj)
This method returns a pointer to a OMXF_Source_type object which contains the OmniMark name of the external function. This method always succeeds. The initial length will always be available from the returned OMXF_Source_type.
OMXF_Source_type * OMXF_GetNameOfReturnType
(OMXF_Environment_type * p_Obj)
Failure possibility:
If the invoked function is declared to return no value, then the returning source object is a null pointer. Otherwise it contains the name of the return type in upper-case.
OMXF_Source_type * OMXF_GetNameOfStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method returns a pointer to an OmniMark OMXF_Source_type object which can be used to retrieve the name of the STREAM item. The OMXF_Source_type object can either be directly freed by the application programmer or it will be garbage-collected when the external function returns.
If the method fails, it returns a null pointer.
OMXF_int OMXF_GetNumberOfArguments
(OMXF_Environment_type * p_Obj)
This method returns the number of arguments associated with that particular call to the function. Unspecified optional arguments are counted. This value can vary with each call of the function.
OMXF_int OMXF_GetNumberOfShelfItems
(object type * p_Obj)
This method returns the number of shelf items. This method never fails. If the return value is zero then the shelf has no items. Otherwise the value will always be greater than zero.
OMXF_Source_type * OMXF_GetOmniMarkVersion
(object type * p_Obj)
This method returns a pointer to an allocated OMXF_Source_type which can be used to get the character representation of the OmniMark version. The length of the OMXF_Source_type will always be available from the returned source.
OMXF_OpaqueShelf_type * OMXF_GetOpaqueArgumentByPosition
(OMXF_Environment_type * p_Obj,
OMXF_int ArgumentNumber)
Failure possibilities:
This is the only way to access opaque arguments. This is because it is possible that a user might want to use two different libraries that happen to define different opaque objects with the same type name in mind. Since the name of an opaque type is an arbitrary thing, used only by the compiler to guarantee correctness, it is not used at all by the shelf-access methods. Instead, opaque arguments must always be accessed by their position in the argument list.
OMXF_OpaqueCopy_fun OMXF_GetOpaqueCopySubfunction
(object type * p_Obj,
OMXF_OpaqueHeader_type * p_OpaqueHeader)
Failure possibility:
In particular circumstances, it is necessary to write external functions that copy an opaque object without explicit knowledge of its copy subfunction. Such situations occur when the copy subfunction of a particular opaque argument can potentially change between calls to the external library function, particularly when the library does not own the opaque object (that is, it was created by another library). To safely copy an opaque object that is not owned by the current library, get the copy subfunction using OMXF_GetOpaqueCopySubfunction and then call that function to copy the object.
OMXF_OpaqueHeader_type * OMXF_GetOpaqueItemReference
(OMXF_OpaqueShelf_type * p_Obj,
OMXF_int ShelfIndex)
Failure possibility:
This method retrieves a pointer to the specified item on the specified OPAQUE shelf.
OMXF_OpaqueRelease_fun OMXF_GetOpaqueReleaseSubfunction
(object type * p_Obj,
OMXF_OpaqueHeader_type * p_OpaqueHeader)
Failure possibility:
In particular circumstances, it is necessary to write external functions that release an opaque object without explicit knowledge of its release subfunction. Such situations occur when the release subfunction of a particular opaque argument can potentially change between calls to the external library function, particularly when the library does not own the opaque object (that is, it was created by another library). To safely release an opaque object that is not owned by the current library, get the release subfunction using OMXF_GetOpaqueReleaseSubfunction and then call that function to release the object.
OMXF_Sink_type * OMXF_GetSinkFromStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method creates a OMXF_Sink_type object for the specified open STREAM shelf item and returns a pointer to it. Through this OMXF_Sink_type object the application programmer writes data to the stream. This process of returning a sink object is equivalent to pushing the open STREAM shelf item onto the current output streams stack. This means that until the OMXF_Sink_type object is freed the STREAM shelf item cannot be closed, removed, cleared or opened.
If the method succeeds, it returns a non-zero value. If it fails, it returns zero.
OMXF_Source_type * OMXF_GetSourceFromStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method creates a OMXF_Source_type object and returns a pointer it. The OMXF_Source_type object will deliever the contents of the specified STREAM shelf item. If the method fails it sets the failure indicator to the appropriate value and returns the pointer value null.
The initial length of the source is always available when the STREAM item is attached to a buffer or a referent.
OMXF_StreamState_type OMXF_GetStateOfStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibility:
This method returns a value indicating the state of the specified STREAM shelf item. If the method failed, OMXF_ss_Failure is returned.
OMXF_StreamShelf_type * OMXF_GetStreamArgument
(OMXF_Environment_type * p_Obj,
const OMXF_String_type * p_ArgumentName)
Failure possibilities:
This method returns a pointer to an object encapsulating the STREAM argument with the specified name. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_StreamShelf_type * OMXF_GetStreamArgumentByPosition
(OMXF_Environment_type * p_Obj,
OMXF_int ArgumentNumber)
Failure possibilities:
This method returns a pointer to an object encapsulating the STREAM argument at the specified position in the declared argument list. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_SwitchShelf_type * OMXF_GetSwitchArgument
(OMXF_Environment_type * p_Obj,
const OMXF_String_type * p_ArgumentName)
Failure possibilities:
This method returns a pointer to an object encapsulating the SWITCH argument with the specified name. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_SwitchShelf_type * OMXF_GetSwitchArgumentByPosition
(OMXF_Environment_type * p_Obj,
OMXF_int ArgumentNumber)
Failure possibilities:
This method returns a pointer to an object encapsulating the SWITCH argument at the specified position in the declared argument list. If the method fails it returns a null pointer and sets the object's failure indicator to the appropriate failure indicator value.
OMXF_SwitchValue_type OMXF_GetSwitchItemValue
(OMXF_SwitchShelf_type * p_Obj,
OMXF_int SwitchItemIndex)
Failure possibility:
This method returns OMXF_sv_True or OMXF_sv_False on success, or OMXF_sv_Failure on failure.
OMXF_ReturnValueType_type OMXF_GetTypeOfReturnValue
(OMXF_Environment_type * p_Obj)
This method returns an enum value based on how the function return type is defined when the function is invoked. It can be useful for writing generic external functions.
OMXF_StreamAttachmentType_type OMXF_GetTypeOfStreamItemAttachment
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method returns the attachment type of the STREAM shelf item. If the method fails, it returns OMXF_sat_Failure.
OMXF_int OMXF_InitializeOpaqueHeader
(object type * p_Obj,
OMXF_OpaqueHeader_type * p_OpaqueHeader,
OMXF_int VersionNumber,
OMXF_OpaqueCopy_fun CopyFunction,
OMXF_OpaqueRelease_fun ReleaseFunction)
Failure possibilities:
This method initializes the header of an OPAQUE value with the specified subfunctions. None of the pointers may be NULL and the constant OMXF_API_VersionNumber must be passed as the VersionNumber argument.
The version number of the API is passed in so that OmniMark knows exactly what the size of the header is. Future versions of OmniMark may add new fields to the header. However, these new fields will not be present in pre-compiled libraries using an older version of the OmniMark External Function API. By passing in the version number, pre-compiled libraries are telling OmniMark not to use the new fields.
This method must be called to initialize the header of every new OPAQUE object. There is no default initialization for the header.
OMXF_int OMXF_InsertNewShelfItem
(object type * p_Obj,
OMXF_int ShelfItemToInsertAfter)
Failure possibilities:
This method inserts a new shelf item after the specified shelf item. The range of legal shelf indexes to insert after range from zero to the number of items in the shelf. If the method succeeds it returns a non-zero value. Otherwise it returns zero.
OMXF_int OMXF_LogMessage
(object type * p_Obj,
char * p_Message,
int MsgLength,
int Severity,
char * p_Class,
int ClassLength)
Failure possibilities:
This is the method that handles user-generated log-messages.
OMXF_int OMXF_OpenStreamItemAsBuffer
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex,
const OMXF_StreamOpenOptionBlock_type * p_OptionBlock)
Failure possibilities:
This method opens the specified STREAM shelf item as a Buffer. If the STREAM shelf item was already open, it is closed first, and then opened. If the method fails the STREAM item is not opened. If the method succeeds it returns an non-zero OMXF_int value. If it fails, it returns zero.
If the p_OptionBlock argument is null, then the default open options are used. Otherwise, the block pointed to by p_OptionBlock will contain the options with which the buffer is to be opened.
OMXF_int OMXF_OpenStreamItemAsFile
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex,
const OMXF_String_type * p_FileName,
const OMXF_StreamOpenOptionBlock_type * p_OptionBlock)
Failure possibilities:
This method opens the specified STREAM shelf item as a file. If the STREAM shelf item was already open, it is closed first, and then opened. If the method fails the STREAM item is not opened. If the method succeeds it returns a nonzero value, and if it fails, it returns zero.
If the p_OptionBlock argument is null, then the default open options are used. Otherwise, the block pointed to by p_OptionBlock will contain the options with which the buffer is to be opened.
OMXF_int OMXF_ReadDataFromSource
(OMXF_Source_type * p_Obj,
OMXF_int DataStorageSize,
OMXF_char * p_DataStorage)
Failure possibility:
This method reads the specified amount of data from the OMXF_Source_type object and places it into the specified data storage area. The method returns the amount of data read as an OMXF_int value. If there is no data left in the OMXF_Source_type object, the method returns the OMXF_int value 0. If a failure occurs, zero is returned as well. The programmer must check the failure indicator to see if a zero return value indicates that there is no data left, or that an error occurred.
OMXF_int OMXF_RemoveKeyOfShelfItem
(object type * p_Obj,
OMXF_int ShelfItemToRemoveKeyFrom)
Failure possibilities:
This method removes the key associated with the specified shelf item. If the method fails the key associated with the shelf item will not have been removed. If the method fails, it will return zero. If it succeeds, it will return a non-zero value.
OMXF_int OMXF_RemoveShelfItem
(object type * p_Obj,
OMXF_int ShelfItemIndex)
Failure possibilities:
This method deletes the specified shelf item. If the method succeeds, it returns a non-zero value. Otherwise it will return zero.
OMXF_int OMXF_ReopenStreamItem
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex,
const OMXF_StreamOpenOptionBlock_type * p_OptionBlock)
Failure possibilities:
This method reopens the STREAM shelf item without changing the attachment. It will append to the text already in the attached object. If the method fails the STREAM item is not reopened. If the method succeeds it returns a non-zero value, and if it fails, it returns zero.
If the p_OptionBlock argument is null, then the default open options are used. Otherwise, the block pointed to by p_OptionBlock will contain the options with which the buffer is to be opened.
OMXF_ResetAppending
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method is used to indicate that a stream should not be opened in appending mode. Since this is the default behavior for a stream, it is only necessary to use this method if an option block has been used to open streams in appending mode, and now needs to be used to open streams in non-appending mode.
This method never fails.
OMXF_ResetBinaryOrdering
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method sets the binary ordering of the stream to be default binary ordering. The method always returns a non-zero value.
OMXF_ResetBreakWidth
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method sets the preferred and maximum break widths to zero. The method never fails.
OMXF_ResetDomainFree
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method is used to indicate that a stream should not be opened in DOMAIN-FREE mode. Since this is the default behavior for a stream, it is only necessary to use this method if an option block has been used to open streams in DOMAIN-FREE mode and now needs to be used to open streams in non-DOMAIN-FREE mode.
This method never fails.
OMXF_ResetStreamOpenOptionBlock
(OMXF_StreamOpenOptionBlock_type * p_Obj)
Resets the option block to the default options for both reopen and open.
OMXF_SetAppending
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method is used to indicate that a stream should be opened in appending mode. The default behavior is to delete the contents of a file whenever it is opened for writing.
This method never fails.
OMXF_SetBinaryBinTextMode
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method indicates the the stream should be opened for writing in binary mode.
OMXF_int OMXF_SetBinaryOrdering
(OMXF_StreamOpenOptionBlock_type * p_Obj,
OMXF_int BinaryOrdering)
Failure possibility:
This method sets the binary ordering of the stream. The integer value must be 0, 1, 2, or 3. The method returns a non-zero OMXF_int value if the method succeeds, and zero on failure. The failure code is set to OMXF_fi_IllegalBinaryOrderingValue and zero is returned if the OMXF_int argument is not one of the four values given above.
OMXF_int OMXF_SetConnectFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_Connect_fun p_ConnectFun)
Failure possibility:
This method sets the "Connect" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_ConnectFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Connect_fun. If the application programmer does not set this subfunction, a default connect subfunction that does nothing is used instead.
The "Connect" subfunction is called prior to the first write to an open stream and also prior to the first close of an open stream if it's not preceded by a write. The "Connect" subfunction is called only once per created stream -- never more than once. Calling it prior to a close ensures that writing zero-length files and other streams works.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetCounterItemValue
(OMXF_CounterShelf_type * p_Obj,
OMXF_int CounterItemIndex,
OMXF_int CounterValue)
Failure possibilities:
This method sets the value of the specified COUNTER shelf item. If the method succeeds it will return a non-zero value. If it fails, zero will be returned.
OMXF_int OMXF_SetCounterReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_int CounterReturnValue)
Failure possibility:
This method sets the return value of the external function to the specified value if it is a COUNTER-returning function. If the function is not a COUNTER-returning function, the method fails.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_SetDefaultBinTextMode
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method indicates the the stream should be opened for writing in the mode that is the default. Since this is the default for a stream, it is only necessary to use this method if an option block object has been used to open streams explicitly in either binary or text mode and now needs to be used to open streams in the default mode. To find out what determines the default mode in opening stream for writing, see the regular OmniMark documentation of BINARY-MODE, TEXT-MODE, and NEWLINE.
The method never fails.
OMXF_int OMXF_SetDisconnectFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_Disconnect_fun p_DisconnectFun)
Failure possibility:
This method sets the "Disconnect" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_DisconnectFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Disconnect_fun. If the application programmer does not set this subfunction, a default Disconnect subfunction that does nothing is used instead.
The Disconnect subfunction is called to indicate that the associated external output stream must cease being prepared for writing. This subfunction is called when the stream is closed or when it is about to go out of scope.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_SetDomainFree
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method is used to indicate that a stream should be opened in DOMAIN-FREE mode.
This method never fails.
OMXF_int OMXF_SetExternalOutputReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_ExternalOutput_type * p_ExtOutput)
Failure possibility:
This method sets the return value of the external function to the specified value if it is an OUTPUT STREAM-returning function. If the function is not an OUTPUT STREAM-returning function, the method fails.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetExternalSourceReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_ExternalSource_type * p_ExtSource)
Failure possibility:
This method sets the return value of the external function to the specified value if it is an EXTERNAL SOURCE-returning function. If the function is not an EXTERNAL SOURCE-returning function, the method fails.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetFormatModifiers
(OMXF_StreamOpenOptionBlock_type * p_Obj,
OMXF_int ModifierValue)
Failure possibilities:
This method is used to activate format modifiers in OMXF_StreamOpenOptionBlock_type objects, and to indicate that all format modifiers should be deactivated (this is done by giving OMXF_obfm_NoFormatModifiers as the only argument).
The OMXF_int argument must be a value corresponding to the "logical ORing" of values in the OMXF_OptionBlockFormatModifier_type type. The "U" and "L" modifiers cannot both be specified. If "L" is specified in the argument, and "U" is already specified on the object, "U" is cleared on the object, and vice versa.
The method returns a non-zero OMXF_int value if the method succeeds, and zero on failure. If the method fails, the failure code is set to one of the above mentioned failure codes.
OMXF_int OMXF_SetHasNameFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_HasName_fun p_HasNameFun)
Failure possibility:
This method sets the "HasName" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_HasNameFun" can not be NULL and must point to a function that has the same function prototype as OMXF_HasName_fun. If the application programmer does not set this subfunction, a default HasName subfunction that returns OMXF_sv_False is used instead.
The "HasName" subfunction is called when OmniMark needs to know whether or not the associated output stream has a name (as by STREAM ... HAS NAME).
If the method succeeds, it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetKeyOfShelfItem
(object type * p_Obj,
OMXF_int ShelfItemIndex,
const OMXF_String_type * p_Key)
Failure possibilities:
This method associates a new key with the specified shelf item. If it succeeds, it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetMaximumBreakWidth
(OMXF_StreamOpenOptionBlock_type * p_Obj,
OMXF_int MaxWidth)
Failure possibilities:
This method sets the maximum break width of the stream to the value of the OMXF_int argument given. The method returns a non-zero OMXF_int value if the method succeeds, and zero on failure. If the argument given is not positive, the failure code is set to OMXF_fi_IllegalBreakWidthValue and a zero value is returned. If the argument given is less than the preferred break width of the stream, the failure code is set to OMXF_fi_MaximumBreakWidthLessThanPreferredWidth and a zero value is returned.
OMXF_int OMXF_SetNameLengthFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_NameLength_fun p_NameLengthFun)
Failure possibility:
This method sets the "NameLength" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_NameLengthFun" can not be NULL and must point to a function that has the same function prototype as OMXF_NameLength_fun. If the application programmer does not set this subfunction, a default NameLength subfunction is used instead. The default NameLength function signals an error and causes OmniMark to terminate.
The "NameLength" subfunction is called when OmniMark needs to know the length of the associated output stream name (if it has one).
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetNameOfFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_NameOf_fun p_NameOfFun)
Failure possibility:
This method sets the "NameOf" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_NameOfFun" can not be NULL and must point to a function that has the same function prototype as OMXF_NameOf_fun. If the application programmer does not set this subfunction, a default NameOf subfunction is used instead. The default NameOf function signals an error and causes OmniMark to terminate.
The "NameOf" subfunction is called when OmniMark needs to know the name of the associated output stream (if it has one).
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetOpaqueItem
(OMXF_OpaqueShelf_type * p_Obj,
OMXF_int ShelfIndex,
OMXF_OpaqueHeader_type * p_OpaqueHeader)
Failure possibilities:
This method sets a pointer to the specified item on the specified OPAQUE shelf.
OMXF_int OMXF_SetOpaqueReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_OpaqueHeader_type * p_OpaqueHeader)
Failure possibilities:
This method is used to return the specified OPAQUE value from the external function. If this is a newly-created OPAQUE value, then the method OMXF_InitializeOpaqueHeader should have already been called on p_OpaqueHeader.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetPreferredBreakWidth
(OMXF_StreamOpenOptionBlock_type * p_Obj,
OMXF_int PreferredBreakWidth)
Failure possibility:
This method sets the preferred break width of the stream to the value of the OMXF_int argument given. The method returns a non-zero OMXF_int value if the method succeeds, and zero on failure. If the argument given is not positive, the failure code is set to OMXF_fi_IllegalBreakWidthValue and a zero value is returned.
OMXF_int OMXF_SetReadFunOfExternalSource
(OMXF_ExternalSource_type * p_Obj,
OMXF_Read_fun p_ReadFun)
Failure possibility:
This method sets the "Read" subfunction of an external function that was declared as an EXTERNAL SOURCE-returning function in the OmniMark program. The pointer "p_ReadFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Read_fun. If the application programmer does not set this subfunction, a default Read subfunction is used instead. The default Read subfunction indicates that the end of input has been reached.
The "Read" subfunction is called to provide input text as it is required by OmniMark. Buffering of text read from an externally-defined source for the purposes of pattern matching is done by OmniMark. Likewise, keeping track of the location information in the source is done by OmniMark.
As of OmniMark Version 4, the size of the buffer given to read subfunctions is guaranteed to be at least 2048 bytes.
OMXF_int OMXF_SetReconnectFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_Reconnect_fun p_ReconnectFun)
Failure possibility:
This method sets the "Reconnect" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_ReconnectFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Reconnect_fun. If the application programmer does not set this subfunction, a default Reconnect subfunction that does nothing is used instead.
The "Reconnect" subfunction is called to indicate that the associated output stream must be prepared for writing after having been disconnected.
The "Reconnect" subfunction is called prior to the first write to a dynamically reopened stream and also prior to the first close of a dynamically reopened stream if it's not preceded by a write. The reconnect subfunction is called once following each dynamic REOPEN of a stream.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetSwitchItemValue
(OMXF_SwitchShelf_type * p_Obj,
OMXF_int SwitchItemIndex,
OMXF_SwitchValue_type SwitchValue)
Failure possibilities:
This method sets the specified SWITCH shelf item to the specified value. If the method fails the shelf item is not changed. The method returns a non-zero value on success and zero on failure.
OMXF_int OMXF_SetSwitchReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_SwitchValue_type SwitchValue)
Failure possibility:
This method sets the return value of the external function to the specified value if it is a SWITCH-returning function. If the function is not a SWITCH-returning function, the method fails. The method returns a non-zero value on success and zero on failure.
OMXF_int OMXF_SetTerminateFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_Terminate_fun p_TerminateFun)
Failure possibility:
This method sets the "Terminate" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_TerminateFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Terminate_fun. If the application programmer does not set this subfunction, a default Terminate subfunction that does nothing is used instead.
The "Terminate" subfunction is called when the lifetime of the external output is about to end and any resources it is using must be released.
For an external output stream, this occurs when the stream actually goes out of scope, and, in general, is preceded by a "close" if the stream is connected. The terminate subfunction is guaranteed to be called when no further references to the output stream exist.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SetTerminateFunOfExternalSource
(OMXF_ExternalSource_type * p_Obj,
OMXF_Terminate_fun p_TerminateFun)
Failure possibility:
This method sets the "Terminate" subfunction of an external function that was declared as an EXTERNAL SOURCE-returning function in the OmniMark program. The pointer "p_TerminateFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Terminate_fun. If the application programmer does not set this subfunction, a default "Terminate" subfunction that does nothing is used instead.
The "Terminate" subfunction is called when the lifetime of the external source is about to end and any resources it is using must be released.
The primary function of the "Terminate" subfunction is to "close" any external file, socket or other connection from which the source was getting input. It can also be used to free up other system resources. OmniMark guarantees that the "Terminate" subfunction of an externally-defined source is always called.
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_SetTextBinTextMode
(OMXF_StreamOpenOptionBlock_type * p_Obj)
This method indicates the stream should be opened for writing in text mode.
OMXF_int OMXF_SetUserInfoOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
void * p_UserInfo)
This method sets a pointer to a user-specified memory location. This pointer is then passed as an argument in all subfunctions. This service is provided as a means of adding persistent data to the external output stream interface.
OMXF_int OMXF_SetUserInfoOfExternalSource
(OMXF_ExternalSource_type * p_Obj,
void * p_UserInfo)
This method sets a pointer to a user-specified memory location. This pointer is then passed as an argument in all subfunctions. This service is provided as a means of adding persistent data to the external output stream interface.
OMXF_int OMXF_SetWriteFunOfExternalOutput
(OMXF_ExternalOutput_type * p_Obj,
OMXF_Write_fun p_WriteFun)
Failure possibility:
This method sets the "Write" subfunction of an external function that was declared as an OUTPUT STREAM-returning function in the OmniMark program. The pointer "p_WriteFun" can not be NULL and must point to a function that has the same function prototype as OMXF_Write_fun. If the application programmer does not set this subfunction, a default Write subfunction is used instead. The default Write function discards all data, without any warning.
The "Write" subfunction is called when the associated output stream should accept some (more) text provided by OmniMark (as by PUT).
If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_SignalExternalFunctionException
(object type * p_Obj,
const char * p_ReasonForException)
Failure possibility:
This method is used to signal to the OmniMark program that the external function has failed in some way. Upon returning from the external function, OmniMark terminates with a fatal error. The string pointed to by "p_ReasonForException" is displayed by OmniMark as additional information for the user running the OmniMark program.
A "reason" for the exception must be provided, even if it is only the zero-length string value.
The method returns a non-zero value on success, and a zero value on failure.
OMXF_int OMXF_SourceAtEnd
(OMXF_Source_type * p_Obj)
This method indicates if the OMXF_Source_type object has no more input in it. If this condition is true then the method returns a non-zero value, otherwise zero is returned. This method always succeeds.
OMXF_int OMXF_StreamItemHasName
(OMXF_StreamShelf_type * p_Obj,
OMXF_int StreamItemIndex)
Failure possibilities:
This method returns a non-zero value if the specified STREAM shelf item exists and has a name. If the specified STREAM shelf item has no name, zero is returned. If a failure occurs zero is also returned. The programmer must check the failure indicator to determine whether a failure indicates that the method failed, or that the OMXF_StreamShelf_type item simply has no name.
OMXF_int OMXF_ToggleSwitchItemValue
(OMXF_SwitchShelf_type * p_Obj,
OMXF_int SwitchItemIndex)
Failure possibilities:
This method toggles the specified SWITCH shelf item from OMXF_sv_True to OMXF_sv_False or from OMXF_sv_False to OMXF_sv_True. If the method succeeds it returns a non-zero value. If it fails, the value of the item is not changed and zero is returned.
OMXF_int OMXF_Write_C_chars_ToCurrentOutput
(OMXF_Environment_type * p_Obj,
OMXF_int DataLength,
const char * p_DataToWrite)
Failure possibilities:
This method writes the specified C characters to the current set of output streams (#CURRENT-OUTPUT). If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_Write_C_chars_ToSink
(OMXF_Sink_type * p_Obj,
OMXF_int AmountOfDataToWrite,
const char * p_Data)
Failure possibilities:
This method writes the specified C characters to the STREAM item associated with the OMXF_Sink_type object. It returns a non-zero OMXF_int value if it succeeds. If it fails, it returns zero.
OMXF_int OMXF_Write_C_chars_ToStreamReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_int DataLength,
const char * p_DataToWrite)
Failure possibilities:
This method writes the specified C characters to the return value of the external function if it is a STREAM-returning function. The text is appended to previously written text, if there is any. If the external function is not a STREAM-returning function, the method fails. The method returns a non-zero value on success, and a zero value on failure.
OMXF_int OMXF_Write_OMXF_chars_ToCurrentOutput
(OMXF_Environment_type * p_Obj,
OMXF_int DataLength,
const OMXF_char * p_DataToWrite)
Failure possibilities:
This method writes the specified OMXF_chars to the current set of output streams (#CURRENT-OUTPUT). If the method succeeds it returns a non-zero value. If it fails, it returns zero.
OMXF_int OMXF_Write_OMXF_chars_ToSink
(OMXF_Sink_type * p_Obj,
OMXF_int AmountOfDataToWrite,
const OMXF_char * p_Data)
Failure possibilities:
This method writes the specified OmniMark characters to the STREAM associated with the OMXF_Sink_type object. It returns a non-zero OMXF_int value if it succeeds. If it fails, it returns zero.
OMXF_int OMXF_Write_OMXF_chars_ToStreamReturnValue
(OMXF_Environment_type * p_Obj,
OMXF_int DataLength,
const OMXF_char * p_DataToWrite)
Failure possibilities:
This method writes the specified OMXF_chars to the return value of the external function if it is a STREAM-returning function. The text is appended to previously written text, if there is any. If the external function is not a STREAM-returning object, the method fails.
If the method succeeds it returns a non-zero value, otherwise it returns zero.
Copyright © OmniMark Technologies Corporation 1988-1999. All rights reserved.
EUM44, release 1, 1997/11/21.