cdesktop/cde/doc/C/guides/man/m3_csa/save.sgm

<!-- $XConsortium: save.sgm /main/4 1996/08/30 15:39:40 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->

<RefEntry Id="CDEMX.MAN73.rsml.1">
<RefMeta>
<RefEntryTitle>csa_save</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>csa_save</Function></RefName>
<RefPurpose>saves calendar entries into an archive file
</RefPurpose>
</RefNameDiv>
<!-- CDE Common Source Format, Version 1.0.0-->
<!-- (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company-->
<!-- (c) Copyright 1993, 1994, 1995 International Business Machines Corp.-->
<!-- (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.-->
<!-- (c) Copyright 1993, 1994, 1995 Novell, Inc.-->
<!-- (c) Copyright 1994 X.400 API Association-->
<RefSynopsisDiv>
<FuncSynopsis Remap="ANSI">
<FuncSynopsisInfo>#include &lt;xcsa.h>
</FuncSynopsisInfo>
<FuncDef>CSA_return_code <Function>csa_save</Function></FuncDef>
<ParamDef>CSA_session_handle <Parameter>session</Parameter></ParamDef>
<ParamDef>CSA_string <Parameter>archive_name</Parameter></ParamDef>
<ParamDef>CSA_uint32 <Parameter>number_attributes</Parameter></ParamDef>
<ParamDef>CSA_attribute *<Parameter>attributes</Parameter></ParamDef>
<ParamDef>CSA_enum *<Parameter>operators</Parameter></ParamDef>
<ParamDef>CSA_boolean <Parameter>delete_entry</Parameter></ParamDef>
<ParamDef>CSA_extension *<Parameter>save_extensions</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<![ %CDE.C.CDE; [
<Para>This optional function is not implemented in the &str-XZ; 1.0 Sample Implementation.
</Para>
]]>
<![ %CDE.C.XO; [
<Para>The
<Function>csa_save</Function> function saves entries from the calendar that is currently
logged on to into the specified archive file.
Only
calendar entries that match all the given criteria are
saved.
</Para>
<Para>The entry handles for the entries are not guaranteed to be
maintained.
If attributes is
<SystemItem Class="Constant">NULL</SystemItem>, all the entries in the calendar will be saved.
If
operators is
<SystemItem Class="Constant">NULL</SystemItem>, this specifies a short hand for an array of operators of
<SystemItem Class="Constant">CSA_MATCH_EQUAL_TO.</SystemItem> Only the owner of the calendar or users with
<SystemItem Class="Constant">CSA_OWNER_RIGHTS</SystemItem> can save entries into an archive file.
</Para>
<Para>The matching criteria are specified by the array of
attributes and the array of operators.
Each operator in
operators specifies how the corresponding attribute value
is to be matched.
The following operators are supported:
</Para>
<VariableList>
<VarListEntry>
<Term>CSA_MATCH_ANY</Term>
<ListItem>
<Para>Matches an entry that contains the corresponding attribute
regardless of the value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_EQUAL_TO</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
equal to the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_NOT_EQUAL_TO</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
not equal to the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_GREATER_THAN</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
greater than the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_LESS_THAN</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
less than the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_GREATHER_THAN_OR_EQUAL_TO</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
greater than or equal to the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_LESS_THAN_OR_EQUAL_TO</Term>
<ListItem>
<Para>Matches an entry that contains an attribute with a value
less than or equal to the corresponding value.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_MATCH_CONTAIN</Term>
<ListItem>
<Para>Applies to character string values only.
It matches an
entry that contains the corresponding substring value.
The
only operators supported for reminder type attributes are
<SystemItem Class="Constant">CSA_MATCH_ANY</SystemItem> and
<SystemItem Class="Constant">CSA_MATCH_EQUAL_TO.</SystemItem> Searching of attributes with opaque data type is not
supported.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>ARGUMENTS</Title>
<RefSect2>
<Title>Session (Session Handle)</Title>
<Para>Opaque session handle that represents a session with the
calendar service.
</Para>
<Para>Session handles are created by a logon function call and
invalidate with a logoff function call.
If the session
handle is invalid then, the error
<SystemItem Class="Constant">CSA_E_INVALID_SESSION_HANDLE</SystemItem> is returned.
</Para>
</RefSect2>
<RefSect2>
<Title>Archive Name (String)</Title>
<Para>A string containing the name of the archive file on the
local system.
</Para>
</RefSect2>
<RefSect2>
<Title>Number Attributes (Uint32)</Title>
<Para>Specifies the size of the arrays pointed to by attributes
and operators.
If attribute argument is
<SystemItem Class="Constant">NULL</SystemItem>, then this must be zero.
</Para>
</RefSect2>
<RefSect2>
<Title>Attributes (Attribute)</Title>
<Para>A pointer to an array of attribute structures specifying
the matching criteria.
If
<Emphasis>number_attributes</Emphasis> argument is zero, then this must be
<SystemItem Class="Constant">NULL</SystemItem>.</Para>
</RefSect2>
<RefSect2>
<Title>Operators (Enum)</Title>
<Para>A pointer to an array of matching operator flags for the
corresponding attribute in attributes.
</Para>
</RefSect2>
<RefSect2>
<Title>Delete Entry (Boolean)</Title>
<Para>Specifies whether the associated entries are to be deleted
from the calendar after being archived into the archive
file.
</Para>
</RefSect2>
<RefSect2>
<Title>Save Extensions (Extension)</Title>
<Para>A pointer to an array of
<StructName Role="typedef">CSA_extension</StructName> structures for this function.
The array may contain both
input extensions for providing additional information to
the function and output extensions for receiving
information from the function.
A value of
<SystemItem Class="Constant">NULL</SystemItem> indicates that the caller is not using any extensions.
See the extensions structure for more information.
</Para>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>RETURN VALUE</Title>
<RefSect2>
<Title>Save Extensions (Extension)</Title>
<Para>If output extensions were passed to the function in the
extensions list, the results from the service will be
available in the extension.
See the extensions structure for more information.
Whether the function succeeded or
not, and, if not, why.
It may be success or one of the
values listed under ERRORS below.
</Para>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>ERRORS</Title>
<Para>The
<Function>csa_save</Function> function returns the following error values:
</Para>
<VariableList>
<VarListEntry>
<Term>CSA_E_DISK_FULL</Term>
<ListItem>
<Para>Insufficient disk space was available to complete
the requested operation (this may refer to local or shared disk space).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_FAILURE</Term>
<ListItem>
<Para>There was a general failure that does not
fit the description of any other error code.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_FILE_EXIST</Term>
<ListItem>
<Para>The specified file in
<Emphasis>csa_save</Emphasis> already exists.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INSUFFICIENT_MEMORY</Term>
<ListItem>
<Para>Insufficient memory was available to complete the requested operation.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_ATTRIBUTE</Term>
<ListItem>
<Para>An attribute was specified that was not defined by this
specification and the implementation does not support the
attribute as an application specific attribute.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_ATTRIBUTE_VALUE</Term>
<ListItem>
<Para>An invalid attribute value was specified for an attribute.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_DATA_EXT</Term>
<ListItem>
<Para>The data extension requested is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_ENUM</Term>
<ListItem>
<Para>A
<StructName Role="typedef">CSA_enum</StructName> value is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_FLAG</Term>
<ListItem>
<Para>A flag value in the
<Symbol Role="Variable">flags</Symbol> argument was invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_FILE_NAME</Term>
<ListItem>
<Para>An invalid file name was specified.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_FUNCTION_EXT</Term>
<ListItem>
<Para>The function extension requested is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_PARAMETER</Term>
<ListItem>
<Para>A function parameter was invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_SESSION_HANDLE</Term>
<ListItem>
<Para>The specified Session Handle is invalid or no longer valid
(e.g., after logging off).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_NO_AUTHORITY</Term>
<ListItem>
<Para>The user has insufficient authority for this function.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_NOT_SUPPORTED</Term>
<ListItem>
<Para>The operation requested is not supported by this implementation.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_SERVICE_UNAVAILABLE</Term>
<ListItem>
<Para>The requested calendar service is unavailable.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_TEXT_TOO_LARGE</Term>
<ListItem>
<Para>The size of the text string passed to the implementation is too large.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNABLE_TO_OPEN_FILE</Term>
<ListItem>
<Para>Unable to open the specified file.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_ATTRIBUTE</Term>
<ListItem>
<Para>An attribute was encountered that is unsupported by the calendar service.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_DATA_EXT</Term>
<ListItem>
<Para>The data extension requested is not supported.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_FLAG</Term>
<ListItem>
<Para>The flag requested is not supported.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_FUNCTION_EXT</Term>
<ListItem>
<Para>The specified function extension is not supported or
<SystemItem Class="Constant">CSA_EXT_REQUIRED</SystemItem> is set.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.csa.csa.h;, &cdeman.csa.add.calendar;, &cdeman.csa.add.entry;, &cdeman.csa.call.callbacks;, &cdeman.csa.delete.calendar;, &cdeman.csa.delete.entry;, &cdeman.csa.free;, &cdeman.csa.free.time.search;, &cdeman.csa.list.calendar.attributes;, &cdeman.csa.list.calendars;, &cdeman.csa.list.entries;, &cdeman.csa.list.entry.attributes;, &cdeman.csa.list.entry.sequence;, &cdeman.csa.logoff;, &cdeman.csa.logon;, &cdeman.csa.look.up;, &cdeman.csa.query.configuration;, &cdeman.csa.read.calendar.attributes;, &cdeman.csa.read.entry.attributes;, &cdeman.csa.read.next.reminder;, &cdeman.csa.register.callback;, &cdeman.csa.restore;, &cdeman.csa.unregister.callback;, &cdeman.csa.update.calendar.attributes;, &cdeman.csa.update.entry.attributes;.</Para>]]>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 01:31:55-->