How can we help?

AxMmServer.MessageDB

In C#, VB.Net, C++ and other compiled languages the namespace for most classes is AXMMCFGLib instead of AxMmServer. For interpreted languages like VBScript, JavaScript or Powershell it is AxMmServer.

Property Type Read/Write Description
Version String Read Version number of the SMS Server
Build String Read Build number of the SMS Server
Module String Read Module name of the SMS Server API module
LastError number Read Completion code of the last called function
AdoConnection object Read The ADO connection to the server database
AdoArchiveConnection object Read The ADO connection to the archive database.

Method Description
GetErrorDescription Get the description of a given error
ResetConnection Reset the connection to the server or archive database
Create Create a new message object
Load Load a message from the server or archive database
Save Saves a new message object to the server database
Delete Delete messages from the server database
Execute Execute an SQL statement in the server database
Count Count messages in the Server database
FindFirstMessage Return the first message that matches the filter
FindNextMessage Return the next message that matches the filter
StartChangeListening Start listening for notifications
StopChangeListening Stop listening for notifications
NotifyStatusUpdate Notify the server that a message status was updated
NotifyNonStatusUpdate Notify the server about a trivial message update
HasStatusUpdate Check if there has been a message status update
HasNonStatusUpdate Check if there has been a trivial message update
GetStatusDescription Look-up the friendly description of the given message status
GetTriggerStatusDescription Look-up the friendly description of the given trigger status
GetDirectionDescription Look-up the friendly description of the given message direction
GetAckStatusDescription Look-up the friendly description of the given ack status

Version property

Return the version number of the SMS Server

Example: 

Set objMessageDB = CreateObject("AxMmServer.MessageDB")
WScript.Echo "SMS Server Version " & objMessageDB.Version & "; Build " & _
  objMessageDB.Build & "; Module " & objMessageDB.Module
...

Build property

Return the build number of the SMS Server.

Example: 

Set objMessageDB = CreateObject("AxMmServer.MessageDB")
WScript.Echo "SMS Server Version " & objMessageDB.Version & "; Build " & _
  objMessageDB.Build & "; Module " & objMessageDB.Module
...

Module property

Return the module name of the SMS Server API module.

Example: 

Set objMessageDB = CreateObject("AxMmServer.MessageDB")
WScript.Echo "SMS Server Version " & objMessageDB.Version & "; Build " & _
  objMessageDB.Build & "; Module " & objMessageDB.Module
...

LastError property

Completion code of the last called function. To find the error description of a given error code, go to the online error codes codes page.

Example: 

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

objMessageDB.CheckReadAccess 
WScript.Echo "CheckReadAccess, result: " &  objMessageDB.LastError

...

AdoConnection property

Returns the ADO connection to the server database in the current state that it is in.

To be sure the ADO connection is opened use ResetConnection before accessing this property.

Example: 

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

objMessageDB.ResetConnection
WScript.Echo "Open, result: " &  objMessageDB.LastError
Set objAdoCon = objMessageDB.AdoConnection

Set objRs = objAdoCon.Execute("...")

...

AdoArchiveConnection property

Returns the ADO connection to the archive database in the current state that it is in.

To be sure the ADO connection is opened use ResetConnection before accessing this property.

Example: 

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

objMessageDB.ResetConnection objConstants.FLAG_RESET_ARCHIVEDATABASE
WScript.Echo "Open, result: " & objMessageDB.LastError
Set objAdoCon = objMessageDB.AdoArchiveConnection

Set objRs = objAdoCon.Execute("...")

...

GetErrorDescription method

GetErrorDescription provides the error description of a given error code.

Parameters:

  • The error code

Return value:

The error string.

Example:

Set objMessageDB = CreateObject("AxMmServer.MessageDB") 
Set objConstants = CreateObject("AxMmServer.Constants") 

Set objMessage = objMessageDB.Create("SMS")
WScript.Echo "Create, result: " & _
    objMessageDB.GetErrorDescription(objMessageDB.LastError)

ResetConnection method

Normally an instance of the MessageDB object will automatically connect to the server or archive database as required. Call this method if there is some database connection error. For instance, if the connection to the database was shortly interrupted. After calling the method, if ‘LastError’ is set to 0 the connection to the database should be ready for use.

Parameters:

Flags (Number, optional; default: 0) – Options to use. Find the flags here.

Return value:

none

Example:

Set objMessageDB = CreateObject("AxMmServer.MessageDB") 
Set objConstants = CreateObject("AxMmServer.Constants") 

objMessageDB.ResetConnection
WScript.Echo "ResetConnection, result: " & _
    objMessageDb.GetErrorDescription(objMessageDB.LastError)

Create method

Create a new message object of the given message type. The message is only created in the server database after calling Save.

The following message types are always available:

  • SMS – To create an SMS message
  • EMAIL – To create an E-mail message
  • FILE – To create a file message
  • SMPPSERVERBIND – To create an SMPP Server bind message

Parameters:

Message type (String) – The type of message to create

Return value:

none

Example:

Set objMessageDB = CreateObject("AxMmServer.MessageDB") 
Set objConstants = CreateObject("AxMmServer.Constants") 

Set objMessage = objMessageDB.Create("SMS")
WScript.Echo "Create, result: " &  objMessageDB.LastError   
If objMessageDB.LastError <> 0 Then
  WScript.Quit
End If

objMessage.ToAddress = "+31612345678
objMessage.Body = "Hello, World"

objMessageDB.Save objMessage
WScript.Echo "Save, result: " & objMessageDB.LastError

Load method

Load a message from the Server database.

Parameters:

Message ID (Number) – Record ID of the message in the server database
Flags (Number, optional; default: 0) – Options to use. Find the flags here.

Return value:

A new Message object.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

Set objMessage = objMessageDB.Load(5)                  ' Load Message with Message ID 5
WScript.Echo "Load, result: " & objMessageDB.LastError
If objMessageDB.LastError <> 0  Then
  WScript.Quit
End If  

WScript.Echo "Message successfully loaded, ID: " & objMessage.ID

Save method

Saves a new message object to the server database.
If the message was originally created new records will be inserted into the server database.
If the message was originally loaded the existing message will be updated.
Change this behavior by using the optional flags parameter.

Parameters:

Message object – The message to save
Flags (Number, optional; default: 0) – Options to use. Find the flags here

Return value:

none

Example:

Set objMessageDB = CreateObject("AxMmServer.MessageDB") 
Set objConstants = CreateObject("AxMmServer.Constants") 

Set objMessage = objMessageDB.Create("SMS")
WScript.Echo "Create, result: " &  objMessageDB.LastError   
If objMessageDB.LastError <> 0 Then
  WScript.Quit
End If

objMessage.ToAddress = "+31612345678
objMessage.Body = "Hello, World"

objMessageDB.Save objMessage
WScript.Echo "Save, result: " & objMessageDB.LastError

Delete method

Delete messages from the server database that match a given message type and filter.
The filter needs to be SQL and an expression that could go after ‘SELECT * FROM Messages WHERE <filter>’
To delete all message the filter should be ‘1=1’.

Parameters:

Type (String) – The message type. Leave empty to delete any message that matches the filter
Filter (String) – A message filter. Cannot be empty

Return value:

Always 0.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

objMessageDB.Delete("", "ID > 46 And ID < 49" )               ' Delete Message with ID=47 or ID=48
WScript.Echo "Delete, result: " & objMessageDB.LastError

Execute method

Execute an SQL statement in the server database.

Parameters:

SQL Statement (String)

Return value:

Number of records affected.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

' Resend all messages in the database
objMessageDB.Execute "UPDATE Messages SET MessageStatus='SCHEDULED', ScheduledTime=SYSDATETIME()"
WScript.Echo "Execute, result: " & objMessageDB.LastError

Count method

Count the number of messages in the Server database. You can apply a filter. When an empty string is passed as filter, all messages are counted. The filter needs to be SQL and an expression that could go after ‘SELECT * FROM Messages WHERE <filter>’

Parameters:

Type (String) – The message type. Leave empty to count any message that matches the filter
Filter (String) – A message filter. Pass an empty string to count all messages.

Return value:

Number of messages.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

' Count all messages in the database with direction Outgoing and status sent 
strFilter = "DirectionID='" & objConstants.MESSAGEDIRECTION_IN & "' AND " & _
            "StatusID='" & objConstants.MESSAGESTATUS_SENT & "'"
numRecords = objMessageDB.Count("", strFilter)               ' Count the records
WScript.Echo "Count, result: " &  objMessageDB.LastError   
If objMessageDB.LastError <> 0 Then
   WScript.Quit
End If

WScript.Echo "Number of messages: " &  numRecords

FindFirstMessage method

Find messages in the server database that match the filter. When an empty string is passed as filter, all messages are selected. The filter can be formatted as an SQL ‘WHERE’ clause.

Parameters :

Type (String) – The message type. Leave empty to count any message that matches the filter
Filter (String) – A message filter. Pass an empty string to find all messages
Order (String, Optional) – Indicates how the results are sorted. Examples: “FromAddress”, “FromAddress ASC”, “ID ASC, FromAddress DESC”
Top (Number, Optional) – Set a limit to the number of records in the result
Flags (Number, Optional; Default: 0) – Options to use. Find the flags here

Return value:

A new Message object.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

' Find all messages
' Start with the first message that matches the qualification
Set objMessage = objMessageDB.FindFirstMessage("SMS", "")
While( objMessageDB.LastError = 0 ) 
  WScript.Echo "Message found: " & objMessage.ID
  WScript.Echo "  Sender: "    & objMessage.FromAddress
  WScript.Echo "  Recipient: " & objMessage.ToAddress
  ' Find next message
  Set objMessage = objMessageDB.FindNextMessage()        
WEnd  

' Find all outgoing messages sorted on Status (Ascending)
WScript.Echo vbCrLf
Set objMessage = objMessageDB.FindFirstMessage("SMS", "DirectionID = '" & _
                 objConstants.MESSAGEDIRECTION_OUT & "'", "Status ASC" )
While( objMessageDB.LastError = 0 ) 
  WScript.Echo "Message found: " & objMessage.ID
  WScript.Echo "  Sender: "    & objMessage.FromAddress
  WScript.Echo "  Recipient: " & objMessage.ToAddress
  Set objMessage   = objMessageDB.FindNextMessage()  
WEnd

FindNextMessage method

Find next message in the server database. This function should be used together with FindFirstMessage.

Parameters:

None

Return value:

A new Message object.

Example:

 Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 
Set objConstants = CreateObject( "AxMmServer.Constants" ) 

' Find all messages
' Start with the first message that matches the qualification
Set objMessage = objMessageDB.FindFirstMessage( "" )     
While( objMessageDB.LastError = 0 ) 
  WScript.Echo "Message found: " & objMessage.ID
  WScript.Echo "  Sender: "    & objMessage.FromAddress
  WScript.Echo "  Recipient: " & objMessage.ToAddress
  ' Find next message
  Set objMessage = objMessageDB.FindNextMessage()        
WEnd  

' Find all outgoing messages sorted on Status (Ascending)
WScript.Echo vbCrLf
Set objMessage = objMessageDB.FindFirstMessage( "DirectionID = '" & _
                 objConstants.MESSAGEDIRECTION_OUT & "'", "Status ASC" )
While( objMessageDB.LastError = 0 ) 
  WScript.Echo "Message found: " & objMessage.ID
  WScript.Echo "  Sender: "    & objMessage.FromAddress
  WScript.Echo "  Recipient: " & objMessage.ToAddress
  Set objMessage   = objMessageDB.FindNextMessage()  
WEnd

StartChangeListening method

Start listening to message related notifications.

Use this when your application should be notified of changes in the messages tables. For instance, when implementing a custom channel or when implementing stand-alone processing. This method should not be used when implementing a trigger script or a web interface.

Without parameter this will listen to general changes to the message table such as inserting or modifying records. When a channel parameter is used it will only listen for changes relating to messages for that specific channel.

Parameters:

Channel ID (String, Optional) – Listen to changes related to a specific channel

Return value:

None.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

objMessageDB.StartChangeListening
If objMessageDB.LastError <> 0 Then
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

Do While True
    If objMessageDB.HasStatusUpdate Then 
        WScript.Echo "A message status was updated"
        Exit Do
    End If
    
    WScrip.Sleep 1
Loop

objMessageDB.StopChangeListening

StopChangeListening method

Stop listening for message related notifications.

Parameters:

None

Return value:

None

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

objMessageDB.StartChangeListening
If objMessageDB.LastError <> 0 Then
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

Do While True
    If objMessageDB.HasStatusUpdate Then 
        WScript.Echo "A message status was updated"
        Exit Do
    End If
    
    WScrip.Sleep 1
Loop

objMessageDB.StopChangeListening

NotifyStatusUpdate method

Send out a notification to the server that a message status was updated. The server will forward this notification to any other listeners.

This notification will trigger the immediate processing of any new or updated messages. It can be used for anything that introduces new messages to the server database or updates the status of existing message in the server database.

This method should not be called from a trigger script.

Parameters:

Channel ID (String, Optional) – The status change was related to a specific channel

Return value:

None

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

Set objSms = objMessageDB.Create("SMS")
objSms.ToAddress = "+3112345678"
objSms.Body = "Send this out right away!"

objMessageDB.Save objSms
If objMessageDB.LastError <> 0
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

objMessageDB.NotifyStatusUpdate

NotifyNonStatusUpdate method

Send out a notification to the server that a message was updated. The server will forward this notification to any other listeners.

This notification will cause the SMS Server Manager to reload the current message view but will not cause a message to be sent or updated.

This method should not be called from a trigger script.

Parameters:

None

Return value:

None

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

objMessageDB.Delete "ID = 100"
If objMessageDB.LastError <> 0
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

objMessageDB.NotifyNonStatusUpdate

HasStatusUpdate method

Check to see if there has been a status update since the last check.

This method requires StartChangeListening to be called first.

Parameters:

None

Return value:

None

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

objMessageDB.StartChangeListening
If objMessageDB.LastError <> 0 Then
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

Do While True
    If objMessageDB.HasStatusUpdate Then 
        WScript.Echo "A message status was updated"
        Exit Do
    End If
    
    WScrip.Sleep 1
Loop

objMessageDB.StopChangeListening

HasNonStatusUpdate method

Check to see if there has been a trivial message update. A message update is trivial if the update does not require the message to be processed or sent.

This method requires StartChangeListening to be called first.

Parameters:

None

Return value:

None

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" ) 

objMessageDB.StartChangeListening
If objMessageDB.LastError <> 0 Then
    WScript.Echo "Error: " & objMessageDB.GetErrorDescription(objMessageDB.LastError)
    WScript.Quit 1
End If

Do While True
    If objMessageDB.HasStatusUpdate Or _ 
       objMessageDB.HasNonStatusUpdate Then 
        WScript.Echo "There was a change in the message database"
        Exit Do
    End If
    
    WScrip.Sleep 1
Loop

objMessageDB.StopChangeListening

GetStatusDescription method

Returns the friendly description of the given StatusID.

Parameters:

A numeric code.

Return value:

The description string.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
' Find first message that matches the qualification
Set objMessage   = objMessageDB.FindFirstMessage("", "" )     
If( objMessageDB.LastError = 0 ) Then
  WScript.Echo "Messgage ID: " & objMessage.ID
  WScript.Echo "Direction ID: " & objMessage.DirectionID
  WScript.Echo "Direction string: " & _
        objMessageDB.GetDirectionDescription( objMessage.DirectionID )
  WScript.Echo "StatusID: " & objMessage.StatusID
  WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
  WScript.Echo "TriggerStatusID: " & objMessage.TriggerStatusID
  WScript.Echo "Trigger status string: " & _
        objMessageDB.GetTriggerStatusDescription( objMessage.TriggerStatusID )
  WScript.Echo "AckStatusID: " & objMessage.AckStatusID
  WScript.Echo "Ack status string: " & _
        objMessageDB.GetAckStatusDescription( objMessage.AckStatusID )
End If

GetTriggerStatusDescription method

Returns the friendly description of the given TriggerStatusID`.

Parameters:

A numeric code.

Return value:

The description string.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
' Find first message that matches the qualification
Set objMessage   = objMessageDB.FindFirstMessage("", "" )     
If( objMessageDB.LastError = 0 ) Then
  WScript.Echo "Messgage ID: " & objMessage.ID
  WScript.Echo "Direction ID: " & objMessage.DirectionID
  WScript.Echo "Direction string: " & _
        objMessageDB.GetDirectionDescription( objMessage.DirectionID )
  WScript.Echo "StatusID: " & objMessage.StatusID
  WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
  WScript.Echo "TriggerStatusID: " & objMessage.TriggerStatusID
  WScript.Echo "Trigger status string: " & _
        objMessageDB.GetTriggerStatusDescription( objMessage.TriggerStatusID )
  WScript.Echo "AckStatusID: " & objMessage.AckStatusID
  WScript.Echo "Ack status string: " & _
        objMessageDB.GetAckStatusDescription( objMessage.AckStatusID )
End If

GetDirectionDescription method

Returns the friendly description of the given DirectionID.

Parameters:

A numeric code.

Return value:

The description string.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
' Find first message that matches the qualification
Set objMessage   = objMessageDB.FindFirstMessage("", "" )     
If( objMessageDB.LastError = 0 ) Then
  WScript.Echo "Messgage ID: " & objMessage.ID
  WScript.Echo "Direction ID: " & objMessage.DirectionID
  WScript.Echo "Direction string: " & _
        objMessageDB.GetDirectionDescription( objMessage.DirectionID )
  WScript.Echo "StatusID: " & objMessage.StatusID
  WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
  WScript.Echo "TriggerStatusID: " & objMessage.TriggerStatusID
  WScript.Echo "Trigger status string: " & _
        objMessageDB.GetTriggerStatusDescription( objMessage.TriggerStatusID )
  WScript.Echo "AckStatusID: " & objMessage.AckStatusID
  WScript.Echo "Ack status string: " & _
        objMessageDB.GetAckStatusDescription( objMessage.AckStatusID )
End If

GetAckStatusDescription method

Returns the friendly description of the given AckStatusID.

Parameters:

A numeric code.

Return value:

The description string.

Example:

Set objMessageDB = CreateObject( "AxMmServer.MessageDB" )
Set objConstants = CreateObject( "AxMmServer.Constants" ) 
  
' Find first message that matches the qualification
Set objMessage   = objMessageDB.FindFirstMessage("", "" )     
If( objMessageDB.LastError = 0 ) Then
  WScript.Echo "Messgage ID: " & objMessage.ID
  WScript.Echo "Direction ID: " & objMessage.DirectionID
  WScript.Echo "Direction string: " & _
        objMessageDB.GetDirectionDescription( objMessage.DirectionID )
  WScript.Echo "StatusID: " & objMessage.StatusID
  WScript.Echo "Status string: " & objMessageDB.GetStatusDescription( objMessage.StatusID )
  WScript.Echo "TriggerStatusID: " & objMessage.TriggerStatusID
  WScript.Echo "Trigger status string: " & _
        objMessageDB.GetTriggerStatusDescription( objMessage.TriggerStatusID )
  WScript.Echo "AckStatusID: " & objMessage.AckStatusID
  WScript.Echo "Ack status string: " & _
        objMessageDB.GetAckStatusDescription( objMessage.AckStatusID )
End If